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

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

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

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

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

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

  • doctest

    • Ещё тесты

  • PEG (не все) и вообще иные ЯП в составе кода Python

  • …

  • чёрт в ступе

Заметка про плагины к VIM-у

• :help packages

  • (vundle, pathogen и т. п.)

• Портал (сегодня утром было 19462 плагина, год назад — 19299)

• Syntastic (на самом деле один из многих)

Установка (в состав ALT входит в виде пакета, можно просто поставить его):

   1 $ mkdir -p ~/.vim/pack/run/start
   2 $ git clone https://github.com/vim-syntastic/syntastic  ~/.vim/pack/run/start/syntastic
   3 $ vim +"helptag ~/.vim/pack/run/start/syntastic/doc"

• run — произвольное имя, не знаю, зачем Брем столько уровней вложенности накрутил

• helptag создаёт в каталоге с документация tag-файл, :help syntastic заработает только после этого

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

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

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

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

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

  • Quick reStructuredText

  • WYSIWYG-редактор на pyQt retext

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

Оформление 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, а примитивные сайтогенераторы

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

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

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

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

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

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

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

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

  • Другое: Pelican,

  • …тысячи их

  • Пример: sourcehut pages

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

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

Д/З

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

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

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

   • Пример