Sphinx

• генератор документации

Ссылки

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

Установка Sphinx на MacOS

1. На macOS установить Homebrew  – пакетный менеджер для macOS.
2. В командной строке терминала выполнить команду:

brew install sphinx-doc

3. Проверить версию Sphinx:

sphinx-build --version

Создание Github-репозитория

1. На macOS установить Git  - систему контроля версий.

brew install git

2. Проверить версию Git:

git -v 

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

git clone <SSH>

Инициализация Sphinx-проекта

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

mkdir docs

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

cd myrepo-docs
sphinx-quickstart

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

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

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

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

• docs – папка со Sphinx-проектом
  • build – папка для генерации выходных документов.
  • source – папка для размещения исходных файлов.
    • _static – папка для размещения исходных файлов, не содержащих исходный код (например, изображения). После генерации выходных документов эта папка служит источником для вложений.
    • _templates – папка для размещения шаблонов документов.
    • conf.py – конфигурационный файл. Содержит ключевые параметры Sphinx-проекта.
    • index.rst – корневой файл. Объединяет документацию воедино в случае, если она разделена на несколько файлов.
  • make.bat –
  • Makefile – содержит инструкции для выходных документов, генереруемых командой make.
• .gitignore – файл с исключениями. Указанные в нем файлы и папки не будут публиковаться в удаленном репозитории.
• README.md – файл с описанием проекта (репозитория).