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

Что уже известно:

• docstrings

• pydoc

  • в т. ч. pydoc -p порт

• pep-257 и pep257 для проверки

• pylint тоже так умеет

• многофайловые модули («пакеты»)

  • __init__.py и __all__

  • import-ы внутри пакетов

⇒ Документация для просмотра, но не для публикации

Отступление от темы: Makefile

На Википедии

Внимание: на лекции всё рассказывалось наспех! Могу устроить отдельную, или:

• видеозапись лекции, в которой рассказывается про make (план этой лекции).

• См. ссылки на учебники в конце, особенно эту

  • у меня получилась такая книжка: main.pdf

• Очень старый (и простой) учебник make из документации по компьютеру БЭСТА-88

Общая идея:

• Объекты:
  • Исходники: то, что редактируем и храним
  • Цели: то, что хотим получить
  • Генераты: то, что нужно сгенерировать для получения целей
• Топологическая зависимость: что из чего делается

  • Например: prog.c → prog

  • Или: a1.c → a1.o; a2.c → a2.o; a1.o, a2.o → prog

    • a1.o, a2.o — генераты

• Рецепт: как что-то из чего-то делается

  • например, как делать .o из .c (при условии, что мы ещё редактируем заголовочный файл inc.h, который включается в file.c):

    file.o:  file.c inc.h
            cc file.c -c -o file.o

  • шаблон рецепта:

    %.o:  %.c
            cc %< -o %@

    где

    • %< — первый из исходников (если нужны используется %^

    • %@ — цель (потому что похоже на мишень, т. е. target)

  • В Makefile обязательны отступы с помощью символов табуляции. Программисты на Python, страдайте!

Подсистема документирования Sphinx

Для начала, их много, подсистем документирования даже на Python.

• Например, Docutils (язык разметки reStructuredText)

• Или всевозможные сайтогенераторы, типа

  • MkDocs (разметка: Markdown)

Но, возможно, Sphinx круче всех.

• Генератор документации Sphinx,

• простая методичка из неё (читать обязательно)

• ещё одна, такая же

Язык разметки: reStructuredText

• «"reStructuredText" is ONE word, not two!», такой же, что и в Docutils

• Шпаргалка

Здесь идёт ±воспроизведение методички. Замечания:

• Инициализация: sphinx-quickstart (возможно, sphinx-quickstart-3)

• Создаваемые файлы:

  • conf.py — настройка sphinx

  • index.rst — титульная страница с директивами reStructuredText

  • Makefile — чтобы можно было делать make html

sphinx-build-3

• Я поменял sphinx-build на sphinx-build-3

• Убрал @ в начале рецептов, чтобы было видно команды

• В частности, sphinx-build-3 -M html . _build собирает документацию безо всякого Makefile

• Разделы «Автоматическая сборка» и «Генерация в формат …» можно не читать ☺

Как добавить техническую документацию, выковырянную из исходников:

• Добавить sphinx.ext.autodoc в config.py:

     1 extensions = [ 'sphinx.ext.autodoc'
     2 ]
  

• Раскомментировать там же «.» в качестве пути к питоньим модулям (или имя каталога с модулем, если они не в «.»):

     1 import os
     2 import sys
     3 sys.path.insert(0, os.path.abspath('.'))
  

• Добавить ссылки на нужные модули. Например, в отдельный файл, на который сослаться из index.rst:

     1 Module contents
     2 ===============
     3 
     4 .. automodule:: packa.core
     5  :members:
     6 
     7 .. automodule:: packa.globals
     8  :members:
  

Остальные расширения

Ах, да: Как писать (несложные) тексты в этом вашем Markdown

Д/З

Семестровый проект должен быть (хотя бы отчасти) документирован.