Sphinx

- 138 words - 1 minute

Create a template

Change directory to the project folder, then:

sphinx-quickstart -l en -p MyProject --sep -a 'John Smith' -r 0.1 doc

For documentation in Spanish:

sphinx-quickstart -l es -p MiProyecto --sep -a 'Juan Pérez -r 0.1 doc

The -l es option will include the following in the conf.py file in the source directory:

language = 'es'

Generate documentation

sphinx-build source build/html -b html

Localization

To translate documentation messages to Spanish:

  1. Create .pot files:

     sphinx-build source build/gettext -b gettext
    
  2. Move .pot files to a locales folder under the source directory:

     mkdir source/locales/es/LC_MESSAGES
     mv build/gettext/*.pot source/locales/es/LC_MESSAGES
    
  3. Rename each .pot file to .po, edit and translate each message. For example:

     #: ../../source/index.rst:7
     msgid "Welcome to MiProyecto's documentation!"
     msgstr "¡Bienvenido a la documentación de MiProyecto!"
    
  4. Build the documentation. If the translation files are not found, use the -v option to debug.