Документация Python неофициальный перевод
Содержание страницы

6. Сборка документацииBuilding the documentation

Необходимо установить Python версии 2.4 или выше; набор инструментов, используемый для сборки документации, написан на Python. Он называется Sphinx, не входит в данное дерево исходников и поддерживается отдельно. Также требуются docutils, предоставляющие базовую разметку, используемую Sphinx, Jinja – шаблонизатор, и, опционально, Pygments – подсветчик кода.

6.1. Использование makeUsing make

К счастью, был подготовлен Makefile, поэтому в Unix, при условии установки Python и Subversion, можно просто выполнить

make html

чтобы извлечь необходимый набор инструментов в подкаталог tools/ и собрать выходные HTML-файлы. Чтобы просмотреть сгенерированный HTML, откройте в любимом браузере корневой индекс build/html/index.html после выполнения «make».

Доступные цели make:

  • «html» – собирает отдельные HTML-файлы для просмотра в автономном режиме.

  • «htmlhelp» – собирает HTML-файлы и файл проекта HTML Help, который можно использовать для преобразования их в один скомпилированный HTML-файл (.chm) – они популярны в Microsoft Windows, но очень удобны на любой платформе.

    Чтобы создать CHM-файл, необходимо запустить Microsoft HTML Help Workshop для сгенерированного файла проекта (.hhp).

  • «latex» – собирает исходные файлы LaTeX для передачи в «pdflatex» для создания PDF-документов.

  • «text» – создаёт обычный текстовый файл для каждого исходного файла.

  • «linkcheck» – проверяет все внешние ссылки на предмет битых, перенаправляющих или некорректных, и выводит эту информацию в stdout, а также в обычный текстовый файл (.txt).

  • «changes» – создаёт обзор всех элементов versionadded/versionchanged/устарело в текущей версии. Предназначен в помощь автору документа «What’s New».

  • «coverage» – создаёт обзор покрытия для модулей стандартной библиотеки и C API.

  • «pydoc-topics» – создаёт модуль Python, содержащий словарь с обычной текстовой документацией для меток, определённых в tools/sphinxext/pyspecific.py – pydoc нуждается в них для отображения справки по темам и ключевым словам.

«make update» обновляет извлечённые из Subversion копии в tools/.

6.2. Без makeWithout make

Потребуется установить пакет Sphinx – либо извлечь его через

svn co http://svn.python.org/projects/external/Sphinx-0.6.5/sphinx tools/sphinx

либо установив его из PyPI.

Затем необходимо установить Docutils – либо извлечь его через

svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils

либо установив его с http://docutils.sf.net/.

Также потребуется Jinja2 – либо извлечь его через

svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2

либо установив его из PyPI.

Опционально можно также установить Pygments – либо извлечь его через

svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments

либо из PyPI по адресу http://pypi.python.org/pypi/Pygments.

Затем создайте выходной каталог, например в build/, и выполните

python tools/sphinx-build.py -b<builder> . build/<outputdirectory>

где <builder> – это один из html, text, latex или htmlhelp (пояснения см. в целях make выше).