Switch to sphinx to be able to translate documentation

[clrh]

We needed to translate in french the Omeka S's documentation, and mkdocs does not fit our needs. Sphinx provides by default all the tools needed to translate with PO files and generate translated documentation. The generated documentation is the same as if it was generated by mkdocs.

Ideally, we think that all the PO files should be in the official documentation repository, and they could be modified on Transifex, so that anyone can participate to translation.

Instructions for translating are written inside translation.md

[jajm]

FYI, french translation has started on https://github.com/biblibre/omeka-s-enduser-fr (on master branch) and is publicly available here: https://omeka-s-enduser-fr.readthedocs.io

[clrh]

To be complete, we did a communication we did to the French community (in French too).

Regards.

[clrh]

Hi,

We would like to have some feedbacks. Please have a look, it would be a real gain for Omeka community who are not English talking people ;).

Thanks.

[zerocrates]

Hi,

This one is complicated for us, since we'd have to change the server-side systems used to build and deploy the docs, as well as the local setups for people working on them. We've also got several other mkdocs projects so it's convenient for us to have the same setup for multiple things.

What in particular does Sphinx provide here that mkdocs doesn't? A system that generates gettext files from the source docs? I'm not really familiar with how localization/translation works in Sphinx.

[jajm]

Hi,

I understand that changing tools is complicated, but I believe having documentation translated in other languages would really benefit Omeka and its users.

What in particular does Sphinx provide here that mkdocs doesn't? A system that generates gettext files from the source docs?

Yes. And a system that generates translated documentation using these gettext files. You can see the basic steps in the translation.md file included in this pull request. And readthedocs supports multi-language documentation with sphinx (example: https://omeka-s-module-search.readthedocs.io/en/latest/, https://omeka-s-module-search.readthedocs.io/fr/latest/

The last time I checked, MkDocs supported translations only for the theme, not for the documentation itself