Sphinx

Sphinx – это генератор документации. Его можно использовать для совместной работы над документами. Ниже описано, как организовать рабочий процесс с использованием сервиса Github.

Ссылки

• Официальная документация 

Подготовка окружения

Подготовить окружение на macOS можно с помощью пакетного менеджера Homebrew . Это можно сделать только один раз. На глобальном уровне для всей системы в целом.

1. Git

# Установить
brew install git

# Проверить версию
git --version

# Обновить
brew update
brew upgrade git

2. Python 3.x

# Установить
brew install python

# Проверить версию
python3 --version

# Обновить
brew upgrade python

3. Pipx

# Установить pipx
brew install pipx

# Проверить версию pipx
pipx --version

# Обновить pipx
python3 -m pip install --upgrade pipx

# Установить приложение
pipx install <название_приложения>

# Проверить установленные приложения
pipx list

# Обновить все приложения
pipx ensureversions

# Удалить приложение
pipx uninsall <название_приложения>

4. Sphinx

# Установить
brew install sphinx-doc
# или
pipx install sphinx-doc

# Проверить версию
sphinx-build --version

# Обновить
pipx upgrade sphinx

Быстрый старт

1. Создать репозиторий

1. Зарегистрироваться на Github . Войти в аккаунт.
2. Создать новый Github-репозиторий. Например, myrepo-docs.
3. Склонировать созданный репозиторий на компьютер:

git clone <SSH>

Подробнее о работе с Github – в официальной документации .

2. Инициализировать проект

1. Внутри склонированного репозитория создать папку docs, чтобы файлы Sphinx-проекта располагались в отдельной директории:

mkdir docs

2. В терминале перейти в созданную директорию myrepo-docs/docs. Выполнить команду для инициализации sphinx-проекта:

cd myrepo-docs/docs
sphinx-quickstart

В процессе инициализации система задаст вопросы:

Примеч.: сведения, отмеченные *, можно будет изменить в файле conf.py.

3. Запушить изменения в удаленный репозиторий:

git status
git add .
git commit -m "build: initialize sphinx, add file structure"
git push -u origin main

Примеч.: пустые папки в удаленный Github-репозиторий не отправляются. Они остаются только в локальном репозитории.

3. Установить расширения

В папке с проектом выполнить команду:

pipx install <название_расширения>

Файловая структура проекта

Файловая структура проекта после выполнения всех предыдущих шагов:

• myrepo-docs
  • docs
    • build
    • source
      • _static
      • _templates
      • conf.py
      • index.rst
    • make.bat
    • Makefile
  • .gitignore
  • README.md

Сборка документации

Ручная сборка

В папке с проектом выполнить команду:

sphinx-build -M html 'docs/source/' 'docs/build/'

Эта команда сгенерирует документацию в формате html. Возьмет исходные файлы из директории docs/source/ и поместит результат в целевую директорию docs/build/.

Если в браузере открыть файл docs/build/html/index.html, то отобразится сайт с документацией.

Автоматическая сборка