ОПИСАНИЕ
SPHINX-DOC

SPHINX-DOC
https://www.sphinx-doc.org/
Sphinx — это инструмент, который позволяет легко создавать документацию, на основе различных форматов файлов.

Первоначально он был создан для документации по Python и имеет отличные возможности для документирования программных проектов на различных языках.

Следует выделить следующие особенности:

  • Выходные форматы: HTML, LaTeX, ePub, Texinfo, справочные страницы, обычный текст .
  • Обширные перекрестные ссылки: семантическая разметка и автоматические ссылки на функции, классы, цитаты, термины глоссария и аналогичную информацию.
  • Иерархическая структура: простое определение дерева документов с автоматическими ссылками на вложенные и соседние каталоги
  • Автоматические индексы: общий индекс, а также индексы языковых модулей
  • Обработка кода: автоматическое выделение с помощью маркера Pygments
  • Расширения: автоматическое тестирование фрагментов кода, включение строк документации из модулей Python (документы API) и многое другое .
  • Добавленные расширения: десятки расширений , добавленных пользователями ; большинство из них можно установить из PyPI
Sphinx — это генератор страниц для публикации в различных форматах: HTML, PDF. Вы используете файлы с кодом, текстовые файлы, файлы с разметкой Markdown и на их основе формируются страницы с документацией.
Используя одинаковый набор исходных файлов Вы сможете сформирвоать документацию и для сайта и для книги
Расширения
Поскольку многим проектам требуются специальные функции в их документации, Sphinx позволяет добавлять «расширения» в процесс сборки, каждое из которых может изменить практически любой аспект обработки документов.

Встраиваемые расширения подключаются ключевыми словами в конфигурации Extensions.



Например можно реализовать:

  • Генерация документации из docstrings
  • Генерировать сводные списки функций, методов, классов
  • Конвертировать изображения приложений
  • Собирать статистику документации
  • Ссылаться на документацию других проектов
  • и т. д.
Тема документации
https://www.sphinx-doc.org/en/master/usage/theming.html
Sphinx поддерживает изменение внешнего вида вывода HTML с помощью тем .

Тема — это набор HTML-шаблонов, таблиц стилей и других статических файлов. У темы есть файл конфигурации, в котором указывается, от какой темы наследоваться, какой стиль выделения использовать.

Темы не зависят от проекта и могут применяться и меняться произвольно.




Тему меняются в файле конфигурации например:

html_theme = "classic"

Также можно применять сторонние темы, они помещаются напрямую или используют принцип установки пакета.

Дополнительные сведения о дизайне тем, включая информацию о написании собственных тем, см . в разделе Разработка тем HTML .
Подключение к другим сервисам
У Sphinx есть API, что позволяет взаимодействовать с ним через указанные директивы
Пример проекта документации
Использование Sphinx в проекте документации по библиотеке классов для датчиков. Проект направлен на развитие языка MicroPython для создания программ на микроконтроллере Micro:Bit.

Поддержка создания программ обработки сигналов с датчиков в концепции Объектно-Ориентированного Программирования. Каждый датчик имеет ассоциированный класс с методами получения и обработки сигнала. Количество и тип методов зависит от функциональности датчика.

Перейти в документацию

Перейти в описание проекта