How to maintain several translations of a documentation set written with Sphinx?

Question

I am starting a personal project and I'd like to provide documentation for my French speaking fellows as well as for the English speaking others.

So how should I organize my directories?

What to separate (I guess sources, some conf items like language for generated navigation links...)?

What not to separate (a maximum of configuration items to avoid duplication)?

Answer 1

We created a Python script to manage translation efforts for our documentation. It creates a directory structure looking like this:

|-- source
    |-- build
    |   `-- html
    |   `-- latex
    |-- i18n
    |   `-- fr
    |       |-- source
    |       |-- build
    |       |   `-- html
    |       |   `-- latex

Basically, the subdirectory under i18n/<lang>/ is mirroring the classic Sphinx directory structure.

The How to translate the Open Object Documentation in your language page in our documentation explains the process.

The documentation is hosted on Launchpad: https://launchpad.net/openobject-doc