Начало работы со сфинксом.

Примечание. Эта статья изначально была опубликована на сайте https://dineshkumarkb.com/tech/generate-professional-python-sdk-documentation-using-sphinx/

Вступление:

Вы работаете над Python SDK или библиотекой, которая будет использоваться несколькими пользователями? Вы когда-нибудь задумывались, как создаются профессиональные документы SDK, такие как boto3, read the docs? Вы хотите создать такой же, как они? Я знаю, ты бы с удовольствием. Пожалуйста, читайте дальше.

Документация Sphinx

Sphinx - это инструмент для создания привлекательной и профессионально привлекательной документации. Это поддерживает несколько форматов вывода, отличные перекрестные ссылки в документации, обработку примеров кода и т. Д.

Sphinx использует reSTructuredText в качестве языка разметки. Расширение файла документации sphinx - .rst.

Установка Sphinx

Предположим, вы уже создали виртуальную среду. Установите sphinx с помощью pip.

$pip install sphinx

Https://pypi.org/project/Sphinx/

Настройка Sphinx

Sphinx предоставляет автоматизированный скрипт для инициализации структуры проекта. Следующая команда инициализирует установку sphinx.

$sphinx-quickstart

Выполнение указанной выше команды запрашивает несколько значений в интерактивной командной строке. Первый вопрос: хотите ли вы разделить каталоги исходного кода и сборки. Вы можете выбрать тот, который вам нужен. Параметр по умолчанию - нет.

Project name : my-sdk
Author name: Dinesh Kumar
Project release[]: 1.0
Project language[en]:
Output:
Creating file /home/dineshkumarkb/MyGitHub/sphinx-env/conf.py.
Creating file /home/dineshkumarkb/MyGitHub/sphinx-env/index.rst.
Creating file /home/dineshkumarkb/MyGitHub/sphinx-env/Makefile.
Creating file /home/dineshkumarkb/MyGitHub/sphinx-env/make.bat.

Finished: An initial directory structure has been created.
You should now populate your master file /home/dineshkumarkb/MyGitHub/sphinx-env/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Следующие файлы будут созданы после установки стартового скрипта.

_build
_static
_templates
conf.py
index.rst
make.bat
Makefile

Файл conf.py имеет все параметры конфигурации, включая темы, расширения и статическую папку для ваших файлов HTML.

...
project = 'my-sdk'
copyright = '2021, Dinesh Kumar'
author = 'Dinesh Kumar'
# The full version, including alpha/beta/rc tags
release = '1.0'
...
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
...
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# -- Options for HTML output -----------------------------------------------
...
html_theme = 'alabaster'
...
html_static_path = ['_static']

index.rst файл - это место, где мы пишем нашу документацию в restructuredtext.

Теперь давайте посмотрим на наиболее часто используемый синтаксис в reSTructuredtext.

Заголовки разделов:

================= Section Headers
----------------- Sub section headers
***************** With overline chapters 
^^^^^^^^^^^^^^^^^ subsub sections
################# Section overline for parts
  • Если используются нижняя и верхняя линия, их длина должна быть одинаковой.
  • Длина подчеркивания должна быть не меньше длины самого заголовка.

При невыполнении вышеуказанных условий он может выдать предупреждение.

Шрифты:

**bold text**
*Italic text*

Списки и маркеры:

# Numbered list item 1
# Numbered list item2
* Unordered list item
* Unordered list item

Блок кода

.. code-block::python
   def func(a, b):
      return a + b

Приведенный выше синтаксис демонстрирует, как блок кода должен быть объявлен в реСТруктурированном тексте.

Расширения

Sphinx поддерживает несколько встроенных расширений для обработки документации. Вы также можете установить дополнительные внешние расширения. Некоторые из встроенных расширений

  • sphinx.ext.autodoc
  • sphinx.ext.todo
  • sphinx.ext.autosectionlabel

Расширения можно добавить в список расширений в conf.py.

Темы

Sphinx поддерживает несколько тем для изменения внешнего вида вашего документа. Пожалуйста, найдите несколько поддерживаемых тем ниже

  • алебастр
  • читать
  • карма
  • сфинксдок

Темы можно изменить в conf.py файле. Мой личный фаворит - readthedocs.

Внутренние ссылки для заголовков

Документация sphinx поддерживает ссылки на внутренние разделы. Для ссылок внутреннего заголовка можно использовать следующий синтаксис.

Indices and tables
==================
* :ref: ``
* :ref: ``
 
Any available title name should be provided between the backticks.

Внешние гиперссылки

`linktext<link url>`

Весь проект представлен по ссылке ниже на GitHub.

Https://github.com/dineshkumarkb/sphinx-doc

Примечание. Не забудьте добавить папку виртуальной среды в список исключений в conf.py. Else sphinx может выдавать множество нежелательных предупреждений при создании сборки.

Строить

HTML

Для создания документации в формате HTML используйте следующую команду.

make html

PDF

make latex

использованная литература

Сгенерированная документация выглядит так.

Я расскажу о размещении документации по сфинксу в другом посте.

Удачного обучения!

Больше контента на plainenglish.io