Приложение I – Установка и настройка Python Sphinx в ОС Windows

Установка

В данном разделе описана установка и настройка Python Sphinx в операционной системе Windows.

  1. Скачайте установочный файл интерпретатора языка программирования Python версии 3.5https://www.python.org.
  1. Запустите файл установки. На первом шаге поставьте галочку напротив Add Python 3.5 to PATH и нажмите Install Now.
  1. Дождитесь завершения установки интерпретатора.
  1. После установки интерпретатора необходимо установить модуль Python Sphinx, для этого откройте командную строку Пуск > cmd и выполните команду pip install sphinx.

На этом установка Python Sphinx закончена, можно переходить к сборке документации. Сборка осуществляется командой:

sphinx-build -b html папка\с\исходными_файлами папка\для\сконвертированных_файлов

Например:

sphinx-build -b html source build\html

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

Перед началом сборки создайте папку docs. Для примера создадим на рабочем столе папку Руководство, а в ней папку docs. Затем откройте командную строку Пуск > cmd и перейдите в папку с руководством, выполнив команду:

cd Desktop\Руководство\docs

Note

Подробнее о работе с командной строкой Windows смотрите Руководство по командной строке Windows.

Выполните команду sphinx-quickstart. Программа задаст ряд вопросов. Все настройки можно будет позже изменить в файле conf.py.

> Корневой каталог документации. По умолчанию текущий каталог.
> Root path for the documentation [.]: Enter

> Сделать ли раздельные папки исходников и готовых страниц - Да
> Separate source and build directories (y/n) [n]: y

> Префикс для директорий с шаблонами и статическими файлами.
> Name prefix for templates and static dir [_]:

> Название проекта. Для начала лучше вводить на латинице.
> Project name:

> Имя автора/авторов. Для начала лучше вводить на латинице.
> Author name(s):

> Версия проекта
> Project version:

> Номер релиза проекта
> Project release [1]:

> Расширение исходного файла. По умолчанию .rst.
> Source file suffix [.rst]:

> Имя мастер-документа. По умолчанию index.rst.
> Name of your master document (without suffix) [index]:

> Генерировать ePub версию документации?
> Do you want to use the epub builder (y/n) [n]:

> Автоматически вставлять docstrings из модулей
> autodoc: automatically insert docstrings from modules (y/n) [n]:

>
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:

>
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:

>
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:

>
> coverage: checks for documentation coverage (y/n) [n]:

> Использовать модуль pngmath для вставки формул в формате png
> pngmath: include math, rendered as PNG images (y/n) [n]:

> Использовать модуль mathjax для вставки формул в формате MathJax
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y

>
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:

> Влючить ссылки на исходный код в документации
> viewcode: include links to the source code of documented Python objects (y/n) [n]:

> Создать Makefile - да
> Create Makefile? (y/n) [y]:

> Сделать ли файл .bat, - да
> Create Windows command file? (Y/n) [y]: y

После выполнения стартового скрипта в папке docs появится следующая структура:

docs
└── build
|       └── html
|               ├── ...
|               └── index.html
└── source
|       ├── _templates
|       ├── _static
|       ├── conf.py
|       └── index.rst
└── Makefile

Makefile — содержит инструкции для генерации результирующего документа командой make.

build — директория, в которую будут помещены файлы в определенном формате после того, как будет запущен процесс их генерации.

source — директория, в которой располагаются исходные файлы.

index.rst — это корень проекта. Он соединяет документацию воедино, если она разделена на несколько файлов.

_static — в эту директорию помещаются все файлы, не являющиеся исходным кодом (например, изображения). Позже создаются связи этих файлов с директорией build.

conf.py — содержит конфигурационные параметры Sphinx, включая те, которые были выбраны при запуске sphinx-quickstart в окне терминала.

Чтобы выполнить сборку документации, перейдите в папку docs и выполните команду:

sphinx-build -b html source build\html

Будет выполнена сборка документации, в терминале появится информация о ходе сборки:

PS C:\Users\mazhartsev\Desktop\Руководство\docs> sphinx-build -b html source build\html
Running Sphinx v1.3.1
making output directory...
loading translations [ru]... done
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in Russian (code: ru) ... done
dumping object inventory... done
build succeeded.

Собранные html-файлы появятся в папаке build\html.

Tip

Для удобства можно создать bat-файл, содержащий строку sphinx-build -b html source build\html. Подробнее смотрите Руководство по командной строке Windows.

Далее смотрите пункт Файл index в разделе Генератор документации Sphinx.