Документирование
Строки документации
- Повторение: почему это не комментарии
pydoc, в т. ч. pydoc -p 123456
- Использование docstrings как хранилищ значимой информации
Собственно техническая документация, но в заданном формате (sphinx и множество других)
doctest — тесты
cmd — документация к командам (а не методам)
- Всевозможные языки программирования и описания структур в составе кода Python
- В настоящее время вытесняется промышленным использованием использованием Sphinx
Техническое документирование
История: Docutils и reStructuredText
Собственно, reStructuredText:
Цель: текстовый документ, который легко читать, но который превращается в хороший гипертекст
- Свойства: сложный (контекстно-зависимый?) расширяемый синтаксис
Простой пример (с оформлением гиперссылки и ссылки на GH issue), он же в опубликованном виде
- Поддержка различных выходных форматов (в т. ч. «книжной» структуры)
WYSIWYM-редактор на pyQt retext (по умолчанию MD, но умеет в reStructuredText, файл должен называться, ….rest)
Sphinx
=reStructuredText (слегка свой диалект)
(см. архивную версию русского перевода)
- +поддержка технического документирования кода
- +раскраска (например, исходного текста)
- +API для расширения
- В частности, темы
Используется для всего, не только для Python.
- Там же:
Специальные команды Sphinx (архив )
например, описание меню и кнопок! (архив )
Пример (см. методичку) / (архив )
Установить sphinx
Запустить sphinx-quickstart и ответить на несколько вопросов
Образуется каталог (по умолчанию source, но часто его называют doc или docs) с первоначальной структурой и конфигурационным файлом
Образуется Makefile (для умеющих в GNU make) и make.bat (для неумеющих в командную строку)
Поправить index.rst
Запустить make html (если есть make)
- В этом Makefile — ±одна команда, её можно и руками запустить:
sphinx-build -M html source build, если есть только python
- В этом Makefile — ±одна команда, её можно и руками запустить:
добавление файла и картинки по примеру из GradeProject2021
BTW: линтер для reStructuredText — тот же rstcheck
встраивается в редакторы, например, vim:Ale
Ещё немного советов про Vim + reStructuredText
Оформление docstrnigs
Примеры IRL: grep -r :param /usr/lib*/python3
(BTW: Napoleon для Google/NumPy docstyle)
добавить "sphinx.ext.autodoc" в список дополнений extensions в файле conf.py
Раскомментировать строчки с указанием пути к исходникам в начале файла conf.py
чудес нет: autodoc просто импортирует все исходники в указанных каталогах; путь должен быть относительным (чаще всего "..")
- ⇒ сборка документации может потребовать все эксплуатационные зависимости (импорт которых не всегда разумно делать в процессе сборки)
использовать директиву .. automodule:: ИмяМодуля, которая приведёт к автоматическому созданию документации по вашему модулю ИмяМодуля.
Перегенерация API-документации — утилита sphinx-apidoc
(если успеем):
doq — порождение docstrings по заголовкам функций и vim-pydocstring
Проблема эксплуатационных зависимостей
Сборка технической документации требует, допустим, Sphinx, но казалось бы не требует модулей, которые нужны для работы самой программы (эксплуатационных зависимостей). Это могут быть GUI-инструментарии, веб-движки или просто тяжёлые пакеты типа torch.
Поскольку autodoc импортирует все исходники, про каждый отсутствующий в сборочном окружении пакет будет отдельная ошибка!
Проблема решается специальной секцией autodoc_mock_imports
Кстати
Я недавно открыл, но ещё не изучал комбинацию reveal.js и Sphinx, а она существует
В частности, sphinx-revealjs
Документация, Слайды, Исходник слайдов в reST
- Вся сила Sphinx (например, раздатки PDF)
Хостинг документации
- Рендеринг reST и Mаrkdown прямо на Git-хостинге
архивная версия русского перевода
Автоматическая публикация документации из git-репозиториев:
Документация в программном продукте
- HTML-виджеты в GUI (в т. ч. markdown-based)
- …
Документация на сайте
readthedocs из отдельного репозитория, содержащего именно документацию / учебник / ЧаВо и т. п.
- «Wiki» на хостинге
- Как правило — часть репоизтория или соседний репозиторий
- Как правило — вообще не Wiki, а примитивные сайтогенераторы с хранением исходников в git
- (а нужно ли больше?)
Markdown (реже ReST, ещё реже всякие старые textile, asciidoc и проч.)
GitHub Pages / GitLab Wiki / …
Пример: SourceHut Wiki
- Основана на git
- просто очередной репозиторий
- или привязанный к ветке существующего репозитория
Поддерживает только MarkDown
Смысл — предоставить push-доступ группе людей (смысл wiki в как можно более быстром доступе)
(BTW, на 2023 год для Wiki в GitLab такой возможности не было, а потом я не проверял ☺ )
- Проект, которому посвящён Wiki, может быть вполне себе Precious Source style
Пример: Документация по самому sr.ht
- Основана на git
- Сайтогененраторы на хостинге
GitHub Pages с jekyll и аналоги
- Сторонние сайтогенераторы + публикация на хостинге (на самом деле, где угодно!)
Пример: sourcehut pages
Вручную: выгрузка архива в определённое место
Автоматичеки: из репозитория с помощью механизмов CI
- Тот же Sphinx
пример + make devserver-global
пример + lektor build -O каталог
- есть админка (на время разработки)!
Д/З
Почитать документацию и попрактиковаться в Sphinx
- Предусмотреть в семестровом проекте
выгонку HTML-документации по API (sphinx.ext.autodoc),
- это в частности означает наличие в репозитории настроенного каталога для sphinx, в котором что-то выгоняется
- статическую документацию по проекту (sphinx, wiki, *-pages, что угодно),
- (пока без публикации)