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)?
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.
- 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.
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
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.