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

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

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

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

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

  • doctest

    • Ещё тесты

  • Системы сборки

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

  • …

  • чёрт в ступе

Заметка про PipEnv

Pipenv: Python Dev Workflow for Humans

• Вариант venv, хранящий окружение и кеши отдельно

• Привязывает окружение к каталогу
• Что-то дополнительно проверяет в окружении
• Не засоряет каталог проекта (только конфиг и статус-файл)

• Хранит всё неизвестно где, и вставляет это неизвестно где в $PATH

Пример.

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

• :help packages

  • (vundle, pathogen и т. п.)

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

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

Установка:

   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:

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

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

  • http://rst.ninjs.org/ и Quick reStructuredText

Sphinx

Сайт

• =reStructuredText

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

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

• Методичка на русском

• Там же:

  • Про reST

  • Специальные команды Sphinx

    • например, описание меню и кнопок!

• Большое HowTo]

Пример (см. методичку)

• установить pip:sphinx

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

  • образуется каталог (по умолчанию source, но часто его называют doc или docs) c ye;ybvb afqkfvb

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

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

• запустить make html (если есть make) или что-то вроде

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

Оформление docstrnigs

AudoDoc

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

• Про docstring-и в HowTo

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

Пример.

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

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

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

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

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

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

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

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

• Read the Docs

• Коротко

• Getting Started with Sphinx

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

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

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

• «Wiki» на хостинге
  • Как правило — часть репоизтория или соседний репощзиторий
  • Как правило — вообще не Wiki, а примитивные сайтогенераторы

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

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

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

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

    • Смысл — предоставить push-доступ группе людей

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

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

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

  • Другое: Pelican,

  • …тысячи их

  • Пример: sourcehut pages

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

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

Д/З

0. Завершить регистрацию семестрового проекта

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

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

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

   • Пример