Hello,
We have apidocs in multiple languages, as per few discussions with @tbrisker we felt that maybe we can drop non English apidocs if those are not being used actively ?
Would like to know thoughts from contributors and users about only keeping English version docs ?
Thank You !
Just to clarify - there are two places where we generate api docs.
The first is those published on the foreman website, e.g. Foreman :: API v2. Dropping additional languages from there will make building our site faster, as well as speed up the release process by a bit.
The second is generated during package build time and shipped with the packages. This will mean packages will build faster then they currently do, as generating api docs for all languages is one of the slowest steps in the build process.
In any case, users will still be able to generate all additional languages locally if they wish by running foreman-rake apipie:cache.
0 voters
For those using the installer I believe that the english would still be generated:
I swear i’ve seen it happen when the rpms are being installed as well, but i’m no 100% sure about that. Should we have some sort of setting that controls what the rake task generates?
We dropped that in 2.0 (except Katello which never did that and always relied on the installer). You have probably seen this in earlier versions.
I feel for API docs English is enough, so I am pro dropping. But some will perhaps feel the need for there own language, so can we adjust the rake job to take a language as argument to create locally what you need and provide documentation somewhere a user can find this quite easily. Perhaps an installer option makes sense, with the installer now doing all rake jobs?
I believe the default when running foreman-rake apipie:cache is to generate the docs in all languages. You can add FOREMAN_APIPIE_LANGS env variable to specify which languages you wish to generate.
If the installer is now running the apipie:cache as well, should we drop it completely from the package build since the docs will be overwritten anyways once the installer runs? Also, should the installer by default only generate English docs, making the installation process shorter?
I think it’s fair to mention in the documentation something like “This documentation is available in English, if you need other language follow instructions.”
I am all for English only.
The installer only regenerates the indexes. Because they’re static HTML files, you need to rebuild index.html, depending on which plugins are installed. It’s not regenerating the actual pages.
Looks like there is quite a consensus around this. Let’s drop the non-english api docs everywhere and add instructions on how to locally generate additional languages if desired.
Please file an issue around this. I think this will be a combination of a packaging issue and documentation.
Following up here with PRs (not intended for 2.2):
why not? I’m fine with pulling this into 2.2
Given this is stabilization week, I just wanted to keep things, well, stable.
I wouldn’t consider this a big destabilizer, assuming tests pass i’m fine with delivering just english in 2.2