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

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

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

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

• Документирование самих исходников

  • Комментарии / Literate programming

  • Документирование API
    • В коде + дополнительно

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

    • Ориентированные на конкретный ЯП, таких немало

• Communication through code (привет дядюшке Бобу)

  • Дисциплина разработки
  • Стиль

  • Структура каталога, наименование и назначение файлов (см., например, структуру GNU Hello)

• Offline-справочники

  • --help и man

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

  • Генераты из документированных исходников

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

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

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

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

  • …Другие системы документирования (много)
• Online
  • Публикация всего вышеописанного
    • Самостоятельно с помощью уже выгнанной HTML-документации

    • Самостоятельно, с помощью специализированного движка (wiki, публикаторы типа Pelican, etc., тысячи их)

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

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

Информационное пространство в совместной разработке

Это опять на целый С/К

• Дисциплина оформления текста программ (code style policy)
• VСS, например, git),
  • дисциплина коммитов
    • в том числе оформления commit message
  • разделение и слияние веток
  • …
• Meta-VCS в стиле социальных сетей, например, merge (или pull?) request-ы с обсуждением
• Issue tracker
• Тематические сообщества (списки рассылки, комнаты мессенждеров, группы в соцсетях, форумы и прочее)
  • Discussions на GH и аналоги
• …

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

(На 2024-11-26 все сайты, использующие ECH — а это, например, весь cloudflare по умолчанию — в России недоступны, надо его выключать)

Cайт

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

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

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

• Общая картина:

  • 

  • В частности, XML: встраивание документации

Пример:

• В примере используется макрос 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 (люто, бешено рекомендую), так что его тоже нужно поставить, как и немного шрифтов

  • В ALT я ставил fonts-ttf-freefont

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

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

0. Создаём шаблон doxygen -g Doxyfile.in (он будет обрабатывается autoconf)

1. Настраиваем этот шаблон (включаем фичи, подставляем макросы)
2. Переоформляем комментарии согласно дисциплине Doxygen

   • у Doxygen есть понятие «документация к файлу» (@file)

   • у Doxygen есть понятие «главная страница»
3. Включаем поддержку Doxygen а autotools

4. Настраиваем генерацию других документов (например, man)

5. Сборка документации запускается по умолчанию

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

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

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

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

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

• Для порождения диаграмм нужен пакет graphviz и (для ALT) шрифт fonts-ttf-freefont (в Арче другой)

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

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

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

Man

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

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

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

• В частности, doxygen (пример)

  • Пришлось пойти на хитрость, т. к. doxygen обычно гененирует man-страницы функций

  • Вариант: написать в отдельном файле с отдельным Doxyfile (так можно использовать Doxygen как Markdown рендерер)

Man и --help

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

• Если пересилить себя и заставить использовать argp из GLibC, в качестве бонуса получим --help, полностью совместимый с help2man

• пример, который был на лекции

• ещё одна методичка

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

Д/З

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

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

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

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

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

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

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

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

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

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

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

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