Начало работы со сфинксом.
Примечание. Эта статья изначально была опубликована на сайте 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
make latex
использованная литература
- Https://www.sphinx-doc.org/en/master/
- Https://sphinx-rtd-theme.readthedocs.io/en/latest/
- Https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
Сгенерированная документация выглядит так.
Я расскажу о размещении документации по сфинксу в другом посте.
Удачного обучения!
Больше контента на plainenglish.io