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

Информационное пространство:
 * Для разработчиков
 * Для сообщества и пользователей
 * Для поддержки продукта

Источники информации:
 * Документирование самих исходников
  * Комментарии / Literate programming
  * Документирование API
   * В коде
   * Дополнительно
   * Популярные системы: [[https://www.sphinx-doc.org|Sphinx]] и [[https://www.doxygen.nl|Doxygen]]
    * А также ориентированные на конкретный ЯП, таких немало
 * Семантика исходников
  * Стиль
  * Структура каталога, наименование и назначение файлов
 * Offline-справочники
  * `--help` и [[man1:man]]
   * О структуре `man` и важности offline-справочников см. какой-нибудь курс по основам Linux
  * Гипертексты: [[https://www.gnu.org/software/texinfo/|Texinfo]] и подобные ему
   * Множество выходных форматов (в первую очередь `LaTeX`), при этом HTML получается ''весьма'' читаемый, но какой-то очень несовременный ☺.
   * Читалка info-файлов [[https://www.gnu.org/software/texinfo/manual/info-stnd/|info]] (кстати, пример HTML там есть)
  * «Книги» — опять-таки texinfo, потому что `LaTeX`.
 * Online
  * Публикация всего вышеописанного
   * Самостоятельно (wiki, публикаторы типа [[https://blog.getpelican.com|Pelican]], etc.)
   * С помощью сервисов совместной разработки: `GitHub`/`GitLab` и их README.md, !GitHub Pages (который github.io) и т. п.
   * С помощью специализированных сервисов: [[https://readthedocs.com|ReadTheDocs]], [[https://www.gitbook.com|Git Book]] и т. п.
== Инструменты интерактивной совместной разработки ==
Должна быть отдельная лекция, но успеем ли?
 * VСS, например, git)
 * Meta-VSC, например, merge (или pull?) request
 * Issue tracker
 * Тематические сообщества (списки рассылки, комнаты мессенждеров, форумы и прочее)
  * Совсем offtop: build-сервера, CI, статистика, вот это всё
== Doxygen ==
[[https://www.doxygen.nl/index.html|Cайт]]
 * [[https://www.doxygen.nl/manual/features.html|Развесистый]] [[https://www.doxygen.nl/manual/commands.html|язык]] и [[https://www.doxygen.nl/manual/doxygen_usage.html|простой инструментарий]] документирования исходников для [[https://www.doxygen.nl/manual/starting.html#step0|различных ЯП]]
 * Используются [[https://www.doxygen.nl/manual/docblocks.html|специальные формы комментариев]]
 * Далее на основании [[https://www.doxygen.nl/manual/config.html|config-файла]] производится сбор блоков документации и [[https://www.doxygen.nl/manual/output.html|выгонка]] соответствующего формата с помощью команды `doxygen конфигурационный_файл`.

Пример:
 * В примере используется макрос [[https://www.gnu.org/software/autoconf-archive/ax_prog_doxygen.html|DX_INIT_DOXYGEN]] для `autotools` из набора [[https://www.gnu.org/software/autoconf-archive/index.html|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` пользуется [[https://graphviz.org|Graphviz]] (люто, бешено рекомендую), так что его тоже нужно поставить, как и немного шрифтов (я ставил семейство Liberation). Сам пакет `doxygen` тоже имеет смысл поставить ☺
 * Для упрощения процедуры на каждом шаге делалась полная пересборка проекта с помощью --(крибле! крабле! бумс!)--` git clean -fd && autoreconf -fisv && ./configure && make`
## Итак, возьмём наш старый [[https://git.sr.ht/~frbrgeorge/libnamegen/commit/5995fe11c362d7964cf8407fb3ce2d41944a6743|проект по генерации фентезийных имён]] `libnamegen` и [[https://git.sr.ht/~frbrgeorge/libnamegen/log|добавим в него документацию]]
Итак, возьмём наш старый [[https://git.sr.ht/~frbrgeorge/namegen|проект по генерации фентезийных имён]] `namegen` и [[https://git.sr.ht/~frbrgeorge/namegen/commit/850ce18aca7fd5de680e693b5d45d5c9f8c204eb|добавим в него документацию]]

 * Посмотреть документацию можно, запустив примитивный сервер на Python:
 {{{
$ python3 -m http.server -d doxygen-doc/html какой-то-порт
 }}}
   … после чего просто зайти браузером на `http://localhost:какой-то-порт`
 * Если вы работаете на сервере практикума, этот порт ''оттуда'' вполне можно пробросить:
 {{{
$ ssh -Lкакой-то-порт:localhost:какой-то-порт user@linuxprac
}}}

== Sphinx ==
Вообще-то [[https://www.sphinx-doc.org|Sphinx]] намного современнее Doxygen, а единственное дополнительное требование — это Python и его модули.

Но ''универсальных'' инструментов ∃ примерно два, и про Sphinx есть в курсе «[[LecturesCMC/PythonDevelopment2020/07_Documetning|Совместная разработка приложений на Python]]»

== Man и --help ==
Варианты написания [[man1:man]]-страницы:
 * Непосредственно — в формате [[https://www.gnu.org/software/groff/|groff]] ([[WP:troff]]), макропакет [[https://www.gnu.org/software/groff/manual/groff.html#man|man]]; [[https://liw.fi/manpages/|простой пример]]
 * На чём-то более синтаксически прозрачном + конвертор — тысячи их (благо просто) — txt2man, [[https://git.sr.ht/~sircmpwn/scdoc|scdoc]], asciidoc, десятки выгонок из markdown, ReST и т. п.
 * В частности, doxygen ([[https://git.sr.ht/~frbrgeorge/namegen/commit/850ce18aca7fd5de680e693b5d45d5c9f8c204eb|пример]])
 * Мы попробуем убить двух зайцев: написать `--help` к программе и обработать это с помощью [[https://www.gnu.org/software/help2man/|help2man]] (соответствующий пакет следует поставить).
  * Если пересилить себя и заставить использовать [[https://www.gnu.org/software/libc/manual/html_node/Argp.html|argp]] из GLibC, в качестве бонуса получим `--help`, ''полностью совместимый'' с `help2man`
  * [[https://www.gnu.org/software/libc/manual/html_node/Argp-Example-3.html|пример, который был на лекции]] 
  * [[https://girishjoshi.io/post/glibc-argument-parsing-argp/|ещё одна методичка]]

Кстати, [[https://www.gnu.org/software/help2man/|help2man]] — в действительности программа для изготовления man-страницы «на скорую руку». В ней ''по умолчанию'' предполагается, что у проекта есть «полноценная» документация в формате `info`!
== Д/З ==
 1.#0 Поизучать [[https://git.sr.ht/~frbrgeorge/namegen/log|пример]] (можно любой другой, например, [[https://git.sr.ht/~frbrgeorge/libnamegen/log|старый вариант]]  ☺)
 1. Взять за основу [[../10_I18n#A.2BBBQ-.2F.2BBBc-|программу для угадывания чисел из прошлого Д/З]]
  * Дописать к ней две функции — перевод из римской системы счисления и обратно
   * Поскольку диапазон `1…100`, проще всего сделать табличку на 100 элементов, ну не знаю, при помощи [[pypi:roman]], :)
  * Научить саму программу принимать из командной строки параметр `-r` для работы в римской системе счисления
  * Задокументировать эти функции (и, возможно, другие, буде они у вас есть), а так же макросы и глобальные переменные (которые сочтёте нужными)
  * Обеспечить программе вменяемый `--help` ('''на двух языках'''!) и `man` (на одном)
  * Заполнить этим help-ом титульную страницу документации
 1. Некоторые подробности
  * Титульную страничку придётся генерировать чем-то боле сложным, чем `LC_ALL=C ./number-game --help`. Например, научить саму программу чему-то вроде `--help-md` (в который она подставляет команды Doxygen) или обработать `--hеlp` чем-то ещё
   * Если ничего не поможет, забейте и тупо скопируйте. Ну не будет у вас титульная страница генератом, возможно, начнёт расходиться с `--help` и `man`, и что?
  * <!> (необязательно, для тех, кто хочет поупражняться программировать на Си) Увеличить диапазон до `1…3999`
 1. Положить всё это хозяйство в подкаталог `11_Documenting` отчётного репозитория