Различия между версиями 10 и 11
Версия 10 от 2021-04-09 21:18:08
Размер: 8261
Редактор: FrBrGeorge
Комментарий:
Версия 11 от 2021-04-10 22:03:30
Размер: 8774
Редактор: FrBrGeorge
Комментарий:
Удаления помечены так. Добавления помечены так.
Строка 113: Строка 113:
'''TODO'''  1.#0 Завершить [[../07_Style#A.2BBBQ-.2F.2BBBc-|регистрацию семестрового проекта]]
 1. Предусмотреть в семестровом проекте
  * выгонку HTML-документации по API (`sphinx.ext.autodoc` или аналоги)
  * статическую документацию по проекту (sphinx, wiki, что угодно)
  * пока без публикации
  * [[https://git.sr.ht/~frbrgeorge/GradeProject2021|Пример]]
 

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

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

Заметка про PipEnv

Pipenv: Python Dev Workflow for Humans

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

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

{i} Пример.

Заметка про плагины к 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.

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

  • установить 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

Пример.

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

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

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

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

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

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

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

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

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

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

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

  • «Wiki» на хостинге
    • Как правило — часть репоизтория или соседний репощзиторий
    • Как правило — вообще не Wiki, а примитивные сайтогенераторы
    • Markdown (реже ReST, ещё реже всякие старые textile, asciidoc и проч.)

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

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

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

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

Д/З

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

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

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

LecturesCMC/PythonDevelopment2021/08_Documenting (последним исправлял пользователь FrBrGeorge 2021-04-10 22:03:30)