Sphinx

Sphinx - генератор документации, например такой и сякой

Установка и сборка

Для установки и создания проекта с доками:

pip install sphinx
sphinx-quickstart

После выполнения команд, в директории проекта появятся следующие файлы:

1. conf.py - конфиг доков

2. index.rst - главная страница доков, содержащая список всех доков проекта

3. Makefile - файл для рендеринга доков в html и другие форматы

Для сборки (рендеринга) доков в html:

make html

Отрендеренные доки находятся в /_build/html

Страницы

После установки, можно создавать страницы в формате .rst:

<!-- guidelines.rst -->
Гайдлайны
================

Именование
***********

SQLAlchemy таблицы
-------------------

Таблицы именуются как модель во множественном числе, ссылка на таблицу - модель во множественном числе + постфикс ``_table``.

Например, для модели ``Venue`` описание таблицы выглядит таким образом:

.. code-block:: python

    venues_table = sa.Table(
        "venues",
        metadata,
        sa.Column("id", sa.BigInteger, primary_key=True, autoincrement=True),
        sa.Column("active", sa.Boolean, default=True),
        sa.Column("title", sa.Unicode),
    )

и добавлять их в содержимое - index.rst:

<!-- index.rst -->
Welcome to sample documentation!
=========================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   guidelines

Синтаксис

Дефолтовый язык разметки в Sphinx - reStructuredText (rst).

Основное преимущество перед Markdown - расширяемость. Например, с помощью rst можно рисовать графики (так и сяк), и документировать API.

Markdown так же можно использовать в качестве языка разметки документов - для этого нужно поставить расширение для базовой поддержки + если нужны таблицы, то расширение для рендеринга таблиц.

Поддержка в IDE

PyCharm

Подсветка rst/md из коробки, но рендеринг русского текса хромает:

VSCode

Ставим расширение, и получаем не такую богатую подсветку, как в PyCharm, зать получаем отрендеренное превью с учетом ссылок, темы и прочего:

В rst определение таблиц сложноватое:

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

+ при расширении колонки, нужно перерисовывать всю таблицу заново

Для генерации и выравнивания разметки таблицы есть специальное расширение - Table Formatter

Темы

• Темы из коробки
• Как в ReadTheDocs
• Тысячи их

Видосы

• Carol Willing - Practical Sphinx - PyCon 2018 - хороший вводный видос: установка, рендеринг разных форматов, обзор расширений, директив, воркфлоу по написанию доков
• Документирование проектов на Python с помощью Sphinx / Николай Карелин [Python Meetup 24.06.2016] - описание работы sphinx, rst-синтаксиса, директив

Еще ссылочки

• https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/ - норм гайд по сетапу
• https://github.com/yoloseem/awesome-sphinxdoc - моды на сфинкс