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

TODO переделать

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

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

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

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

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

  • doctest

    • Ещё тесты

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

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

  • чёрт в ступе

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

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

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

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

    • TODO пример

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

    • TODO пример

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

  • Quick reStructuredText

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

Sphinx

Сайт

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

• +поддержка технического документирования кода
• +раскраска (например, исходного текста)
• +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

TODO добавление файла и картинки.

Оформление 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:: ИмяМодуля, которая приведёт к автоматическому созданию документации по вашему модулю ИмяМодуля.

BTW: Настройка syntasitc для проверки rst-файлов sphinx-ом:

• Положить в ~/.vimrc или выполнять всякий раз

  • :let g:syntastic_rst_checkers = ["sphinx"]

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

• Read the Docs

• Коротко

• 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 и проч.)

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

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

• Сторонние сайтогенераторы + публикация на хостинге
  • Тот же Sphinx

  • Другое: Pelican,

  • …тысячи их

Д/З

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

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

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

   • Пример