Вызов sphinx-build

Скрипт sphinx-build создаёт набор документации Sphinx. Вызывается он таким образом:

$ sphinx-build [options] sourcedir builddir [filenames]

где sourcedir - sphinx source directory, builddir - каталог, в котором будет располагаться собранная документация. Чаще всего Вам не понадобится определять какие-либо filenames.

Скрипт sphinx-build имеет несколько опций:

-b buildername

Наиболее важная опция: выбор “строителя”. Наиболее популярные:

html
Создаёт HTML страницы. Вариант по умолчанию
dirhtml
Создаёт HTML страницы, но с одним каталогом на документ. Полезно для красивых URL (без .html) если это поддерживается вебсервером.
singlehtml
Создаёт один HTML, содержащий всю информацию.
htmlhelp, qthelp, devhelp, epub
Создаёт HTML файлы с дополнительной информацией для создания набора документации в одном из этих форматов.
latex
Создаёт исходники LaTeX, которые можно скомпилировать в PDF документ при помощи pdflatex.
man
Создаёт manual pages в формате groff для UNIX систем.
texinfo
Создаёт файлы Texinfo, которые могут быть преобразованы в файлы Info при помощи makeinfo.
text
Создаёт простые текстовые файлы.
gettext
Создаёт каталоги сообщений типа gettext (файлы .pot).
doctest
Запускает все доктесты в документации, если активировано расширение doctest.
linkcheck
Проверяет целостность всех внешних ссылок.

Смотри builders в поисках полного списка всех “строителей”, поставляемых вместе с Sphinx. Расширения могут добавлять свои собственные “строители”.

-a

Если указана, то выходные файлы всегда буду перезаписаны. По умолчанию перезаисываются только файлы для новых или изменённых исходников. (Это может не работать для всех “строителей”)

-E

Не использовать сохранённое sphinx environment (структура, кеширующая все кросс-ссылки), а перестроить его заново. По умолчаню прочитываются и парсятся только новые и изменённые за последнее время файлы.

-t tag

Определяет тег tag. Это актуально для директив only, которые включают только его содержимое, если этот тег установлен.

New in version 0.6.

-d path

Так как Sphinx должен прочитать и распарсить все исходные файлы преед тем, как он создаёт выходные файлы, разбираемые исходные файлы кэшируются как “doctree pickles”. Обычно, эти файлы располагаются в каталоге с именем .doctrees в каталоге для сборки. Этой опцией Вы можете указать другой каталог для кэша (одни и те же doctree могут быть использованы разными “строителями”).

-c path

Не обращать внимание на файл conf.py в каталоге с исходниками, а использовать вместо него настроечный каталог. Обратите внимание, что многие другие файлы и пути, поставляемые конфигурацией указаны относительно настроечного каталога, так что они тоже должны находиться в этом каталоге.

New in version 0.3.

-C

Не обращать внимание на конфигурационный файл. Опции получать при помощи опции -D.

New in version 0.5.

-D setting=value

Переопределить настройки в файле conf.py. Значением должна быть строка или значение словаря. В последнем случае поддериваются имена настроек и ключи вроде этого: -D latex_elements.docclass=scrartcl. Для логических величин используйте значения 0 или 1.

Changed in version 0.6: Значением теперь может быть значение словаря.

-A name=value

Присваивает name значение value в HTML шаблонах.

New in version 0.5.

-n

Запускает в режиме nit-picky(“придирчивом”). На данный момент выдаёт предупреждения для всех отсутствующих ссылок.

-N

Отменить цветной вывод. (Для Windows, цветной вывод в любом случае отключён.)

-q

Не выводить ничего в стандартный вывод, только предупреждения и ошбики в стандартный вывод ошибок.

-Q

Не выводить ничего в станадртный вывод и подавалять предупреждения. Только ошибки будут выводиться в стандартный вывод ошибок.

-w file

Записать предупреждения (и ошибки) в указанный файл, дополнительно к выводу в стандартный вывод ошибок.

-W

Перевести предупреждения в ошибки. Это означает, что сборка прекращается при первом предупреждении и sphinx-build завершает работу со статусом 1.

-P

(Полезно только для отладки.) Запустить отладчик Python, pdb, если при постройке возникает необработанное исключение.

Вы так же можете указать одно или более имён файлов в командной строке после исходного каталога и каталога для сборки. Sphinx в таком случае попробует создать только эти выходные файлы (и их зависимости).

Опции Makefile

Файлы Makefile и make.bat, создаваемые программой sphinx-quickstart, обычно вызывают программу sphinx-build только с опциями -b и -d. Однако, они поддерживают следующие переменные, которые могут настроить их поведение:

PAPER

Значение для :confval:`latex_paper_size`.

SPHINXBUILD

Команда, которую надо использовать вместо sphinx-build.

BUILDDIR

Каталог для сборки, который нужно использовать вместо выбранного в sphinx-quickstart.

SPHINXOPTS

Дополнительные опции для sphinx-build.

Вызов sphinx-apidoc

Программа sphinx-apidoc автоматически генерирует документацию API для пакета Python. Вызывается он таким образом:

$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]

где packagedir это путь к пакету, который нужно задокументировать, а outputdir это каталог, где должны располагаться выходные файлы. Все pathnames являются путями, которые должны быть проигнорированны в процессе генерации.

Скрипт sphinx-apidoc имеет следующие опции:

-o outputdir

Указывает каталог, где должны располагаться выходные файлы.

-f, --force

Обычно sphinx-apidoc не переписывает файлы. Используйте эту опцию для того, чтобы перезаписать все создаваемые файлы.

-n, --dry-run

При наличии этой опции никакие файлы не будут перезаписаны.

-s suffix

Эта опция определяет суффикс для имён выходных файлов. По умолчанию это rst.

-d maxdepth

Определяет максимальную глубину содержания при генерациии.

-T, --no-toc

Не создавать файл содержания modules.rst. Не имеет смысла при опции --full.

-F, --full

Эта опция заставляет sphinx-apidoc создать полный проект Sphinx, используя тот же механизм, что и sphinx-quickstart. Большинство настроечных значений имеют значения по умолчанию, но наиболее важные из них можно определить при помощи следующих опций.

-H project

Задаёт имя проекта, которое будет размещено в созданных файлах (см :confval:`project`).

-A author

Задаёт имя автора(ов), которое будет размещено в созданных файлах (см :confval:`copyright`).

-V version

Задаёт версию проекта, которое будет размещено в созданных файлах (см :confval:`version`).

-R release

Задаёт релиз проекта, которое будет размещено в созданных файлах (см :confval:`release`).