Документирование

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

• Повторение: почему это не комментарии

  • pydoc, в т. ч. pydoc -p 123456

• Использование docstrings как хранилищ значимой информации

  • Собственно техническая документация, но в заданном формате (sphinx и множество других)

  • doctest

    • Ещё тесты

  • PEG (не все, но часто) и другие задания грамматик (например, https://wiki.python.org/moin/LanguageParsing)

  • Всевозможные языки программирования и описания структур в составе кода Python
  • …

  • чёрт в ступе

Техническое документирование

• История: Docutils и reStructuredText

• Собственно, reStructuredText:

  • Цель: текстовый документ, который легко читать, но который превращается в хороший гипертекст

    • Пример из проекта rstcheck

  • Свойства: сложный (контекстно-зависимый?) расширяемый синтаксис

    • Простой пример (с оформлением гиперссылки и ссылки на GH issue), он же в опубликованном виде

  • Поддержка различных выходных форматов (в т. ч. «книжной» структуры)

  • Quick reStructuredText

  • WYSIWYM-редактор на pyQt retext (по умолчанию MD, но умеет в reStructuredText, файл должен называться, ….rest)

Sphinx

Сайт

• =reStructuredText (слегка свой диалект)

  • ( на 2024-03-31 недоступно, см. архивную версию )

• +поддержка технического документирования кода
• +раскраска (например, исходного текста)
• +API для расширения
  • В частности, темы

Используется для всего, не только для Python.

• Методичка на русском (архив )

• Там же:

  • Про reST (архив )

  • Специальные команды Sphinx (архив )

    • например, описание меню и кнопок! (архив )

• Большое HowTo

Пример (см. методичку) / (архив )

• Установить sphinx

• Запустить sphinx-quickstart и ответить на несколько вопросов

  • Образуется каталог (по умолчанию source, но часто его называют doc или docs) с первоначальной структурой и конфигурационным файлом

  • Образуется Makefile (для умеющих в GNU make) и make.bat (для неумеющих в командную строку)

• Поправить index.rst

• Запустить make html (если есть make)

  • В этом Makefile — ±одна команда, её можно и руками запустить:

    • sphinx-build -M html source build, если есть только python

• добавление файла и картинки по примеру из GradeProject2021

BTW: линтер для reStructuredText — тот же rstcheck

• встраивается в редакторы, например, vim:Ale

Ещё немного советов про Vim + reStructuredText

Оформление docstrnigs

AutoDoc

• Примеры IRL: grep -r :param /usr/lib*/python3

• Про docstring-и в HowTo

• (BTW: Napoleon для Google/NumPy docstyle)

Пример

• добавить "sphinx.ext.autodoc" в список дополнений extensions в файле conf.py

• Раскомментировать строчки с указанием пути к исходникам в начале файла conf.py

  • чудес нет: autodoc просто импортирует все исходники в указанных каталогах; путь должен быть относительным (чаще всего "..")

  • ⇒ сборка документации может потребовать все эксплуатационные зависимости (импорт которых не всегда разумно делать в процессе сборки)

• использовать директиву .. automodule:: ИмяМодуля, которая приведёт к автоматическому созданию документации по вашему модулю ИмяМодуля.

Перегенерация API-документации — утилита sphinx-apidoc¶

Проблема эксплуатационных зависимостей

Сборка технической документации требует, допустим, Sphinx, но казалось бы не требует модулей, которые нужны для работы самой программы (эксплуатационных зависимостей). Это могут быть GUI-инструментарии, веб-движки или просто тяжёлые пакеты типа torch.

• Поскольку autodoc импортирует все исходники, про каждый отсутствующий в сборочном окружении пакет будет отдельная ошибка!

• Проблема решается специальной секцией autodoc_mock_imports

• Пример

Хостинг документации

• Read the Docs

• Коротко ( на 2024-03-31 «в процессе обновления», см. архивную версию )

• Getting Started with Sphinx

(если успеем):

• doq — порождение docstrings по заголовкам функций и vim-pydocstring

• тысячи их…

Документация в программном продукте

• Help в командной строке (например, в argparse или cmd)

• argparse-manpage, Sphinx manual page output

• HTML-виджеты в GUI (в т. ч. markdown-based)
• …

Документация на сайте

• readthedocs
• «Wiki» на хостинге
  • Как правило — часть репоизтория или соседний репозиторий
  • Как правило — вообще не Wiki, а примитивные сайтогенераторы с хранением исходников в git
    • (а нужно ли больше?)

  • Markdown (реже ReST, ещё реже всякие старые textile, asciidoc и проч.)

  • Пример: «Wiki» на sr.ht

    • Основана на git
      • просто очередной репозиторий
      • или привязанный к ветке существующего репозитория

    • Поддерживает только MarkDown

    • Смысл — предоставить push-доступ группе людей (смысл wiki в как можно более быстром доступе)

      • Проект, которому посвящён Wiki, может быть вполне себе Precious Source style

    • Пример: Документация по самому sr.ht

    • (BTW, на 2023 год для Wiki в GitLab такой возможности не было)

• Сайтогененраторы на хостинге

  • GitHub Pages с jekyll и аналоги

• Сторонние сайтогенераторы + публикация на хостинге (на самом деле, где угодно!)

  • Пример: sourcehut pages

    • Вручную: выгрузка архива в определённое место

    • Автоматичеки: из репозитория с помощью механизмов CI

  • Тот же Sphinx

  • Pelican

    • пример + make devserver-global

  • Lektor

    • пример + lektor build -O каталог

    • есть админка (на время разработки)!

  • Nikola

  • …тысячи их

Д/З

1. Предусмотреть в семестровом проекте

   • выгонку HTML-документации по API (sphinx.ext.autodoc),

     • это в частности означает наличие в репозитории настроенного каталога для sphinx, в котором что-то выгоняется
   • статическую документацию по проекту (sphinx, wiki, *-pages, что угодно),
   • (пока без публикации)

   • Пример