> **Источник:** https://python-all.ru/2.6/documenting/building.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

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

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

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

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

```python
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. Без make

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

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

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

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

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

либо установив его с [http://docutils.sf.net/](https://python-all.ru/2.6/documenting/building.html).

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

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

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

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

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

либо из PyPI по адресу [http://pypi.python.org/pypi/Pygments](https://python-all.ru/2.6/documenting/building.html).

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

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

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