python-sphinx учебник
Начало работы с python-sphinx
Поиск…
замечания
В этом разделе представлен обзор того, что такое python-sphinx, и почему разработчик может захотеть его использовать.
Следует также упомянуть о любых крупных предметах в python-sphinx и ссылаться на связанные темы. Поскольку документация для python-sphinx является новой, вам может потребоваться создать начальные версии этих связанных тем.
Установка или настройка
Поскольку Sphinx доступен в Индексе пакетов Python , его можно установить с помощью pip :
pip install Sphinx
или вы также можете установить с помощью easy_install
easy_install -U sphinx
Затем вы можете проверить, что он был правильно установлен, выполнив следующую команду:
> sphinx-quickstart --version
Sphinx v1.4.1
Прежде чем продолжить, вам нужно следовать определенному стилю кода для python PEP 8 . Если вы следовали руководству PEP 8, вы можете определить структуру документа в сфинксе и начать создавать свою документацию .
Быстрый старт
Для начала перейдите в корневой каталог проекта и запустите:
$ sphinx-quickstart
Вы получите варианты создания документации для своего проекта. Для настройки по умолчанию выполните следующие команды:
Prompt Choice
> Root path for the documentation [.]: <ENTER>
> Separate source and build directories (y/N) [n]: y
> Name prefix for templates and static dir [_]: <ENTER>
> Project name: an_example_pypi_project
> Author name(s): Andrew Carter
> Project version: 0.0.1
> Project release [0.0.1]: <ENTER>
> Source file suffix [.rst]: <ENTER>
> Name of your master document (without suffix) [index]: <ENTER>
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: n
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
> todo: write “todo” entries that can be shown or hidden on build (y/N) [n]: n
> coverage: checks for documentation coverage (y/N) [n]: n
> pngmath: include math, rendered as PNG images (y/N) [n]: n
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/N) [n]: y
> Create Makefile? (Y/n) [y]: n
> Create Windows command file? (Y/n) [y]: n
После успешного выполнения вы можете обнаружить файл config.py в своей директории doc / source вашего проекта. Этот файл имеет контроль над базовой структурой того, как будет создан ваш документ при выполнении команды сборки, как показано ниже.
$ sphinx-build -b html sourcedir builddir
Подробные инструкции доступны по адресу: https://pythonhosted.org/an_example_pypi_project/sphinx.html.