Первоначальные настройки#

Советую работать на Linux (Debian/Ubuntu), либо использовать WSL на Windows 10. Об установке WSL можете почитать в документации от Microsoft.

Если вы используете другие операционные системы, то поищите в официальной документации Sphinx описание установки для вашего случая. Дальше все действия будем выполнять в терминале/консоли.

Note

Если вы используете WSL на Windows 10, то не забудьте перед установкой ввести в консоли bash.

Bash

Чтобы установить Sphinx, необходим Python. Самую последнюю версию можно скачать на официальном сайте.

Далее мы устанавливаем виртуальное окружение, чтобы не засорять компьютер. Введите команду:

sudo apt install python3.9-venv.

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

cd repos/sphinx-example

Где repos и sphinx-example — названия ваших папок.

Внутри sphinx-example мы и развернём наше виртуальное окружение. Введите команду:

python3 -m venv venv.

После этого заходите в виртуальное окружение с помощью команды:

source venv/bin/activate.

Note

Команду выше придётся повторять каждый раз, когда вы будете возвращаться к работе над документацией. Иначе команды, которые мы рассмотрим ниже, не будут работать.

После этого вам нужно установить:

  1. sphinx — сам генератор документации.

  2. sphinx-autobuild — эта команда позволяет генерировать сайт «вживую». То есть после внесения каких-то изменений в документе вы сможете увидеть их на своём локальном хосте.

  3. Тему для вашей документации. Sphinx использует темы, которые создают другие люди. Самому подобрать тему можно на на сайте Sphinx Themes. В данной статье мы будем использовать furo. Если по какой-то причине она вам не понравилась или не подходит для ваших задач, то можете использовать другую. Советую ещё тему pydata. Использовал её на всех предыдущих проектах с документацией.

    Статья универсальная для любой темы. Даже если что-то будет отличаться, то ответы на свои вопросы вы сможете найти в документации на странице выбранной темы.

Команда для установки в конечном виде будет выглядеть так:

pip3 install sphinx sphinx-autobuild furo.

Какие-то оставшиеся дополнения мы будем устанавливать по ходу написания документации.