Информационное пространство: документирование

Информационное пространство:

• Для разработчиков
• Для сообщества и пользователей
• Для поддержки продукта

Источники информации:

• Документирование самих исходников
  • Комментарии / Literate programming
  • Документирование API
    • В коде
    • Дополнительно

    • Популярные системы: Sphinx и Doxygen

      • А также ориентированные на конкретный ЯП, таких немало
• Семантика исходников
  • Стиль
  • Структура каталога, наименование и назначение файлов
• Offline-справочники

  • --help и man

    • О структуре man и важности offline-справочников см. какой-нибудь курс по основам Linux

  • Гипертексты: Texinfo и подобные ему

    • Множество выходных форматов (в первую очередь LaTeX), при этом HTML получается весьма читаемый, но какой-то очень несовременный ☺.

    • Читалка info-файлов info (кстати, пример HTML там есть)

  • «Книги» — опять-таки texinfo, потому что LaTeX.

• Online
  • Публикация всего вышеописанного

    • Самостоятельно (wiki, публикаторы типа Pelican, etc.)

    • С помощью сервисов совместной разработки: GitHub/GitLab и их README.md, GitHub Pages (который github.io) и т. п.

    • С помощью специализированных сервисов: ReadTheDocs, Git Book и т. п.

  • Инструменты интерактивной совместной разработки
    • VSC, например, git)
    • Meta-VSC, например, merge (или pull?) request
    • Issue tracker
    • Тематические сообщества (списки рассылки, комнаты мессенждеров, форумы и прочее)
  • Совсем offtop: build-сервера, CI, статистика, вот это всё

Doxygen

Cайт

• Развесистый язык и простой инструментарий документирования исходников для различных ЯП

• Используются специальные формы комментариев

• Далее на основании config-файла производится сбор блоков документации и выгонка соответствующего формата с помощью команды doxygen конфигурационный_файл.

Пример:

• В примере используется макрос DX_INIT_DOXYGEN для autotools из набора Autoconf Archive (пакет autoconf-archive в ALT).

  • Как сказано в документации, он обеспечивает для autoconf

    • проверку существования doxygen,

    • набор переключателей для ./configure (делать/не делать PDF, HTML и т. п. см. ./configure --help),

  • а для Makerfile.am — набор целей (в частности, doxygen-doc:)

• В примере много файлов с расширением .in (например, Doxyfile.in). Если такие файлы без расширения .in добавить в AC_CONFIG_FILES(), ./configure забесплатно сконструирует их из .in-файлов, подставив туда различные макросы, типа @PACKAGE_NAME@ или @DX_DOCDIR@

• Для создания диаграмм doxygen пользуется Graphviz (люто, бешено рекомендую), так что его тоже нужно поставить, как и немного шрифтов (я ставил семейство Liberation). Сам пакет doxygen тоже имеет смысл поставить ☺

• Для упрощения процедуры на каждом шаге делалась полная пересборка проекта с помощью крибле! крабле! бумс! git clean -fd && autoreconf -fisv && ./configure && make

Итак, возьмём наш старый проект по генерации фентезийных имён libnamegen и добавим в него документацию

• Посмотреть документацию можно, запустив примитивный сервер на Python:

  $ python3 -m http.server -d doxygen-doc/html какой-то-порт

  • … после чего просто зайти браузером на http://localhost:какой-то-порт

• Если вы работаете на сервере практикума, этот порт оттуда вполне можно пробросить:

  $ ssh -Lкакой-то-порт:localhost:какой-то-порт user@linuxprac

Sphinx

Вообще-то Sphinx намного современнее Doxygen, а единственное дополнительное требование — это Python и его модули.

Но универсальных инструментов ∃ примерно два, и про Sphinx есть в курсе «Совместная разработка приложений на Python»

Man и --help

• Варианты написания man-страницы:

  • Непосредственно — в формате groff (troff), макропакет man; простой пример

  • На чём-то более синтаксически прозрачном + конвертор — тысячи их (благо просто) — txt2man, asciidoc, десятки выгонок из markdown, ReST и т. п.
  • В частности, doxygen (не рекомендуется. though:)

Мы попробуем убить двух зайцев: написать --help к программе и обработать это с помощью help2man (соответствующийпакет следует поставить).

Кстати, help2man — в действительности программа для изготовления man-страницы «на скорую руку». В ней по умолчанию предполагается, что у проекта есть «полноценная» документация в формате info!

Д/З

0. Поизучать пример (можно любой другой ☺)

1. Взять за основу программу для угадывания чисел из прошлого Д/З

   • Дописать к ней две функции — перевод из римской системы счисления и обратно

     • Поскольку диапазон 1…100, проще всего сделать табличку на 100 элементов, ну не знаю, при помощи roman,

   • Научить саму программу принимать из командной строки параметр -r для работы в римской системе счисления

   • Задокументировать эти функции (и, возможно, другие, буде они у вас есть), а так же макросы и глобальные переменные (которые сочтёте нужными)

   • Обеспечить программе вменяемый --help (на двух языках!) и man (на одном)

   • Заполнить этим help-ом титульную страницу документации
2. Некоторые подробности

   • Есть проблема: у Doxygen нет понятия include (есть, но оно значит другое), поэтому титульную страничку придётся генерировать чем-то боле сложным, чем LC_ALL=C ./number-game --help. Например, научить саму программу чему-то вроде --help-md (в который она подставляет команды Doxygen) или обработать --hеlp чем-то ещё

     • Если ничего не поможет, забейте и тупо скопируйте. Ну не будет у вас manpage генератом, возможно, начнёт расходиться с --help, и что?

   • (необязательно, для тех, кто хочет поупражняться программировать на Си) Увеличить диапазон до 1…3999

3. Положить всё это хозяйство в подкаталог 10_Documenting отчётного репозитория