Публикация сайтов с документацией в Sphinx#

Установка sphinx на Windows#

Инструкция на английском на официальном сайте библиотеки: https://www.sphinx-doc.org/en/master/usage/installation.html#windows-other-method

Установка python#

По умолчанию на windows python не установлен. Нужно проверить факт установки, если действительно его нет, то нужно установить. Для проверки версии python:

  1. Открыть терминал. ⊞Win-r и написать cmd

  2. В терминале написать python --version и нажать Enter

  3. Если python установлен, то напечатается его версия.

Инструкция для установки https://docs.python-guide.org/starting/install3/win/

Установка пакета sphinx глобально#

  1. Открыть терминал. ⊞Win-r и написать cmd

  2. В терминале написать pip install -U sphinx

Использование виртуального окружения#

При установке Sphinx при помощи pip, рекомендуется использовать virtual environments (виртуальное окружение), которое изолирует устанавливаемые пакеты от системных. Для создания виртуального окружения в папке .venv используй следующую команду.

python -m venv .venv

Запуск нового проекта#

В пустой папке создать виртуальное окружение для Python и установить требуемые инструменты. Для этого в cmd терминале выбрать папку и выполнить следующие команды:

$python -m venv .venv $source .venv/bin/activate (.venv) $ python -m pip install sphinx

Если все прошло успешно, CLI для sphinx будет установлен, для проверки нужно выполнить команду

(.venv) $ sphinx-build --version

Создание шаблона документации#

Из терминала выполнить следующую команду:

sphinx-quickstart docs

Визард задаст уточняющие вопросы и создаст внутреннюю структуру документации:

docs
├── build
├── make.bat
├── Makefile
└── source
   ├── conf.py
   ├── index.rst
   ├── _static
   └── _templates

Смысл сгенерированных файлов и папок следующий:

build/ На данном этапе папка пуста, в ней будет хранится сгенерированные статический html файлы с готовой документацией.

make.bat and Makefile Скрипты обеспечивающие выполнение некоторых общие действий движка Sphinx, таких как отрисовка контента.

source/conf.py Скрипт на питоне, в котором содержится конфигурация проекта. К примеру в этом скрипте можно задавать тему оформления и устанавливать модули расширения.

source/index.rst Корневой документ проекта, который является главной страницей и хранит оглавление со ссылками на другие вложенные страницы сайта визитки.

Генерация документации#

Нужно отредактировать главную страницу, добавив заголовок и какой-то текст

Заголовок
=========
Текст страницы

Сгенерировать документацию можно такой командой: sphinx-build -M html docs/source/ docs/build/ Теперь можно просто открыть готовый html файл docs/build/html/index.html в браузере

Элементы оформления#

Полная инструкция тут: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

Самое основное - ниже

Заголовки#

Заголовок первого уровня
========================


Заголовок второго уровня
------------------------


Заголовок третьего уровня
~~~~~~~~~~~~~~~~~~~~~~~~~

Нумерованные и ненумерованные списки#

List markup (ref) is natural: just place an asterisk at the start of a paragraph and indent properly. The same goes for numbered lists; they can also be autonumbered using a # sign:

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues