.. _invocation: Вызов sphinx-build ========================== Скрипт :program:`sphinx-build` создаёт набор документации Sphinx. Вызывается он таким образом:: $ sphinx-build [options] sourcedir builddir [filenames] где *sourcedir* - :term:`sphinx source directory`, *builddir* - каталог, в котором будет располагаться собранная документация. Чаще всего Вам не понадобится определять какие-либо *filenames*. Скрипт :program:`sphinx-build` имеет несколько опций: .. program:: sphinx-build .. option:: -b buildername Наиболее важная опция: выбор "строителя". Наиболее популярные: **html** Создаёт HTML страницы. Вариант по умолчанию **dirhtml** Создаёт HTML страницы, но с одним каталогом на документ. Полезно для красивых URL (без ``.html``) если это поддерживается вебсервером. **singlehtml** Создаёт один HTML, содержащий всю информацию. **htmlhelp**, **qthelp**, **devhelp**, **epub** Создаёт HTML файлы с дополнительной информацией для создания набора документации в одном из этих форматов. **latex** Создаёт исходники LaTeX, которые можно скомпилировать в PDF документ при помощи :program:`pdflatex`. **man** Создаёт manual pages в формате groff для UNIX систем. **texinfo** Создаёт файлы Texinfo, которые могут быть преобразованы в файлы Info при помощи :program:`makeinfo`. **text** Создаёт простые текстовые файлы. **gettext** Создаёт каталоги сообщений типа gettext (файлы ``.pot``). **doctest** Запускает все доктесты в документации, если активировано расширение :mod:`~sphinx.ext.doctest`. **linkcheck** Проверяет целостность всех внешних ссылок. Смотри :ref:`builders` в поисках полного списка всех "строителей", поставляемых вместе с Sphinx. Расширения могут добавлять свои собственные "строители". .. option:: -a Если указана, то выходные файлы всегда буду перезаписаны. По умолчанию перезаисываются только файлы для новых или изменённых исходников. (Это может не работать для всех "строителей") .. option:: -E Не использовать сохранённое :term:`sphinx environment` (структура, кеширующая все кросс-ссылки), а перестроить его заново. По умолчаню прочитываются и парсятся только новые и изменённые за последнее время файлы. .. option:: -t tag Определяет тег *tag*. Это актуально для директив :rst:dir:`only`, которые включают только его содержимое, если этот тег установлен. .. versionadded:: 0.6 .. option:: -d path Так как Sphinx должен прочитать и распарсить все исходные файлы преед тем, как он создаёт выходные файлы, разбираемые исходные файлы кэшируются как "doctree pickles". Обычно, эти файлы располагаются в каталоге с именем :file:`.doctrees` в каталоге для сборки. Этой опцией Вы можете указать другой каталог для кэша (одни и те же doctree могут быть использованы разными "строителями"). .. option:: -c path Не обращать внимание на файл :file:`conf.py` в каталоге с исходниками, а использовать вместо него настроечный каталог. Обратите внимание, что многие другие файлы и пути, поставляемые конфигурацией указаны относительно настроечного каталога, так что они тоже должны находиться в этом каталоге. .. versionadded:: 0.3 .. option:: -C Не обращать внимание на конфигурационный файл. Опции получать при помощи опции ``-D``. .. versionadded:: 0.5 .. option:: -D setting=value Переопределить настройки в файле :file:`conf.py`. Значением должна быть строка или значение словаря. В последнем случае поддериваются имена настроек и ключи вроде этого: ``-D latex_elements.docclass=scrartcl``. Для логических величин используйте значения ``0`` или ``1``. .. versionchanged:: 0.6 Значением теперь может быть значение словаря. .. option:: -A name=value Присваивает *name* значение *value* в HTML шаблонах. .. versionadded:: 0.5 .. option:: -n Запускает в режиме nit-picky("придирчивом"). На данный момент выдаёт предупреждения для всех отсутствующих ссылок. .. option:: -N Отменить цветной вывод. (Для Windows, цветной вывод в любом случае отключён.) .. option:: -q Не выводить ничего в стандартный вывод, только предупреждения и ошбики в стандартный вывод ошибок. .. option:: -Q Не выводить ничего в станадртный вывод и подавалять предупреждения. Только ошибки будут выводиться в стандартный вывод ошибок. .. option:: -w file Записать предупреждения (и ошибки) в указанный файл, дополнительно к выводу в стандартный вывод ошибок. .. option:: -W Перевести предупреждения в ошибки. Это означает, что сборка прекращается при первом предупреждении и ``sphinx-build`` завершает работу со статусом 1. .. option:: -P (Полезно только для отладки.) Запустить отладчик Python, :mod:`pdb`, если при постройке возникает необработанное исключение. Вы так же можете указать одно или более имён файлов в командной строке после исходного каталога и каталога для сборки. Sphinx в таком случае попробует создать только эти выходные файлы (и их зависимости). Опции Makefile ---------------- Файлы :file:`Makefile` и :file:`make.bat`, создаваемые программой :program:`sphinx-quickstart`, обычно вызывают программу :program:`sphinx-build` только с опциями :option:`-b` и :option:`-d`. Однако, они поддерживают следующие переменные, которые могут настроить их поведение: .. describe:: PAPER Значение для :confval:`latex_paper_size`. .. describe:: SPHINXBUILD Команда, которую надо использовать вместо ``sphinx-build``. .. describe:: BUILDDIR Каталог для сборки, который нужно использовать вместо выбранного в :program:`sphinx-quickstart`. .. describe:: SPHINXOPTS Дополнительные опции для :program:`sphinx-build`. .. _invocation-apidoc: Вызов sphinx-apidoc =========================== Программа :program:`sphinx-apidoc` автоматически генерирует документацию API для пакета Python. Вызывается он таким образом:: $ sphinx-apidoc [options] -o outputdir packagedir [pathnames] где *packagedir* это путь к пакету, который нужно задокументировать, а *outputdir* это каталог, где должны располагаться выходные файлы. Все *pathnames* являются путями, которые должны быть проигнорированны в процессе генерации. Скрипт :program:`sphinx-apidoc` имеет следующие опции: .. program:: sphinx-apidoc .. option:: -o outputdir Указывает каталог, где должны располагаться выходные файлы. .. option:: -f, --force Обычно sphinx-apidoc не переписывает файлы. Используйте эту опцию для того, чтобы перезаписать все создаваемые файлы. .. option:: -n, --dry-run При наличии этой опции никакие файлы не будут перезаписаны. .. option:: -s suffix Эта опция определяет суффикс для имён выходных файлов. По умолчанию это ``rst``. .. option:: -d maxdepth Определяет максимальную глубину содержания при генерациии. .. option:: -T, --no-toc Не создавать файл содержания ``modules.rst``. Не имеет смысла при опции :option:`--full`. .. option:: -F, --full Эта опция заставляет sphinx-apidoc создать полный проект Sphinx, используя тот же механизм, что и :program:`sphinx-quickstart`. Большинство настроечных значений имеют значения по умолчанию, но наиболее важные из них можно определить при помощи следующих опций. .. option:: -H project Задаёт имя проекта, которое будет размещено в созданных файлах (см :confval:`project`). .. option:: -A author Задаёт имя автора(ов), которое будет размещено в созданных файлах (см :confval:`copyright`). .. option:: -V version Задаёт версию проекта, которое будет размещено в созданных файлах (см :confval:`version`). .. option:: -R release Задаёт релиз проекта, которое будет размещено в созданных файлах (см :confval:`release`).