Сборка переведенной документации

Документация Sphinx рекомендует последовательно использовать две команды для сборки переведенной документации (в нашем примере на русском языке):

set SPHINXOPTS=-D language=ru

make html

Первая команда устанавливает язык документации, а вторая запускает сборку.

Проблема с этим методом заключается в том, что Sphinx записывает результат в папку, указанную в файле make.bat, и эта папка одинакова для всех языков.

Поэтому воспользуемся другим методом, предполагающим больший контроль над различными параметрами сборки. Мы запустим sphinx-build напрямую и укажем язык и папку сборки в одной команде.

  1. Перед сборкой новой документации вы можете удалить все из папки _build/html, так как ранее сгенерированные файлы нам больше не нужны.

  2. Чтобы собрать русскоязычную документацию с помощью sphinx-build, выполните следующую команду:

    sphinx-build -b html -D language=ru -d _build/doctrees/ru/ . _build/html/ru/
    

    Эта команда указывает Sphinx собрать html-документацию (-b html) на русском языке (-D language=ru) и поместить результат в папку _build/html/ru/ (. _build/html/ru/). Команда также указывает папку для файлов doctrees (-d _build/doctrees/ru/), иначе Sphinx записывает файлы doctrees в ту же папку, что и html файлы.

  3. Чтобы собрать документацию на португальском языке в _build/html/pt_BR/, выполните следующую команду:

    sphinx-build -b html -D language=pt_BR -d _build/doctrees/pt_BR/ . _build/html/pt_BR/
    
  4. Также нам нужна англоязычная документация в папке _build/html/en/:

    sphinx-build -b html -D language=en -d _build/doctrees/en/ . _build/html/en/
    

Размещение локализованной документации в отдельных папках, как описано выше, поможет нам в дальнейшем разработать переключатель языка.

Если теперь заглянуть в папки locale/ru/LC_MESSAGES и locale/pt_BR/LC_MESSAGES, то можно увидеть, что там появились файлы index.mo и easter-egg.mo. Sphinx генерирует эти двоичные файлы из файлов .po, а затем использует файлы .mo для сборки. Вам не нужно ничего делать с файлами .mo, просто игнорируйте их.