building.md

1> **Источник:** https://python-all.ru/3.1/documenting/building.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 6. Сборка документации89Необходимо установить Python версии 2.4 или выше; набор инструментов, используемый для сборки документации, написан на Python. Он называется *Sphinx*, не входит в данное дерево исходников и поддерживается отдельно. Также требуются docutils, предоставляющие базовую разметку, используемую Sphinx, Jinja – шаблонизатор, и, опционально, Pygments – подсветчик кода.1011## 6.1. Использование make1213К счастью, был подготовлен Makefile, поэтому в Unix, при условии установки Python и Subversion, можно просто выполнить1415```python16make html17```1819чтобы извлечь необходимый набор инструментов в подкаталог *tools/* и собрать выходные HTML-файлы. Чтобы просмотреть сгенерированный HTML, откройте в любимом браузере корневой индекс *build/html/index.html* после выполнения «make».2021Доступные цели make:2223> - «html» – собирает отдельные HTML-файлы для просмотра в автономном режиме.24> - «htmlhelp» – собирает HTML-файлы и файл проекта HTML Help, который можно использовать для преобразования их в один скомпилированный HTML-файл (.chm) – они популярны в Microsoft Windows, но очень удобны на любой платформе.25>26>   Чтобы создать CHM-файл, необходимо запустить Microsoft HTML Help Workshop для сгенерированного файла проекта (.hhp).27> - «latex» – собирает исходные файлы LaTeX для передачи в «pdflatex» для создания PDF-документов.28> - «text» – создаёт обычный текстовый файл для каждого исходного файла.29> - «linkcheck» – проверяет все внешние ссылки на предмет битых, перенаправляющих или некорректных, и выводит эту информацию в stdout, а также в обычный текстовый файл (.txt).30> - «changes» – создаёт обзор всех элементов versionadded/versionchanged/устарело в текущей версии. Предназначен в помощь автору документа «What’s New».31> - «coverage» – создаёт обзор покрытия для модулей стандартной библиотеки и C API.32> - «pydoc-topics» – создаёт модуль Python, содержащий словарь с обычной текстовой документацией для меток, определённых в *tools/sphinxext/pyspecific.py* – pydoc нуждается в них для отображения справки по темам и ключевым словам.3334«make update» обновляет извлечённые из Subversion копии в *tools/*.3536## 6.2. Без make3738Потребуется установить пакет Sphinx – либо извлечь его через3940```python41svn co http://svn.python.org/projects/external/Sphinx-0.6.5/sphinx tools/sphinx42```4344либо установив его из PyPI.4546Затем необходимо установить Docutils – либо извлечь его через4748```python49svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils50```5152либо установив его с [http://docutils.sf.net/](https://python-all.ru/3.1/documenting/building.html).5354Также потребуется Jinja2 – либо извлечь его через5556```python57svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja258```5960либо установив его из PyPI.6162Опционально можно также установить Pygments – либо извлечь его через6364```python65svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments66```6768либо из PyPI по адресу [http://pypi.python.org/pypi/Pygments](https://python-all.ru/3.1/documenting/building.html).6970Затем создайте выходной каталог, например в *build/*, и выполните7172```python73python tools/sphinx-build.py -b<builder> . build/<outputdirectory>74```7576где *\<builder\>* – это один из html, text, latex или htmlhelp (пояснения см. в целях make выше).77