Hello,
Currently, building packages takes a fairly long time. A large portion of that time is spent generating localized API docs (I believe @ehelms has some measurements of exactly how much). Which raises the question - should we stop shipping localized docs and only ship the English version by default? are people actually using the localized version? Is there a different approach that would work (e.g. splitting the apidoc to s separate package and only build it for stable releases)?
1 Like
My main question around this is whether we can avoid the need altogether. Currently the API docs are all static HTML so we must generate all files. apipie-rails, which we use to generate it, can also output swagger (OpenAPI 2.0) files with localized JSON files. Swagger also has a UI and since it uses Javascript I was wondering if the translations could be done inside the browser rather than statically. I think this would greatly reduce the complexity and perhaps also standardize our API. Perhaps we would look into extending apipie-rails to generate OpenAPI 3.0 as well but I have no idea how complex that would be.
1 Like
Exactly this. I think I’ve brought this several times. And the answer was that this is just matter of resources. Indeed someone needs to find time to look into this.
I agree it is worth considering to change the way we deliver API docs.
For a short term what @tbrisker suggests makes sense. While it is easy to build additional language with
$ FOREMAN_APIPIE_LANGS=<lang> foreman-rake apipie:cache
it may be acceptable to make the translations opt-in.
Another options:
- let it build at run-time once it is requested by the browser. Apipie can do that
- we can possibly spawn new process at server start that builds the missing cache
Another thing to consider is whether we can also do the same for cache index that is build during the installation and slows down the installer and the updates. The difference is we use the localized index data to localize Hammer help where users can have different demand for the availability of translations.
2 Likes
Does apipie cache hold any translations for hammer? What I mean is if we simply drop all the languages except English, could a Chinese hammer user see an English message as a regresion?
If not, than it’s no brainer for me. Developer docs in English is fine IMHO.
Yes, apipie cache is localized and Hammer is using it. https://example.com/apidoc/v2.zh_CN.json is typically something hammer tries to download with Chinese locales. I still believe Foreman is able to generate the file on the fly. I actually checked and if the use_cache on
https://github.com/theforeman/foreman/blob/develop/config/initializers/apipie.rb#L12 is false Foreman can generate the page on the fly and on my instance it takes about 9s. However I was not able to set it up to generate and store if the cache is missing which would be IMO best solution for the translations. Maybe patch in Apipie could fix that.
That sounds like it could be a really valuable improvement - we don’t build and ship the localized version in advance but it gets “lazy built” the first time it is used.