Различия между версиями 4 и 5
Версия 4 от 2022-12-06 17:34:12
Размер: 12663
Редактор: FrBrGeorge
Комментарий:
Версия 5 от 2022-12-06 17:48:19
Размер: 12828
Редактор: FrBrGeorge
Комментарий:
Удаления помечены так. Добавления помечены так.
Строка 85: Строка 85:
  * Пришлось пойти на хитрость, т. к. doxygen обычно гененирует man-страницы ''функций''
Строка 86: Строка 87:
Мы попробуем убить двух зайцев: написать `--help` к программе и обработать это с помощью [[https://www.gnu.org/software/help2man/|help2man]] (соответствующий пакет следует поставить). Мы попробуем убить двух зайцев: написать `--help` к некоторой программе и обработать это с помощью [[https://www.gnu.org/software/help2man/|help2man]] (соответствующий пакет следует поставить).

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

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

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

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

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

        • А также ориентированные на конкретный ЯП, таких немало
  • Семантика исходников
    • Стиль
    • Структура каталога, наименование и назначение файлов
  • 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-VSC в стиле социальных сетей, например, merge (или pull?) request
  • Issue tracker
  • Тематические сообщества (списки рассылки, комнаты мессенждеров, группы в соцсетях форумы и прочее)

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

Cайт

Пример:

  • В примере используется макрос 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 и добавим в него документацию

  • Посмотреть документацию можно, запустив примитивный сервер на 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-страницы функций

Man и --help

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

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

Д/З

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

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

    • Дописать к ней две функции — перевод из римской системы счисления и обратно
      • Поскольку диапазон 1…100, проще всего сделать табличку на 100 элементов, ну не знаю, при помощи roman, :)

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

    • Задокументировать эти функции (и, возможно, другие, буде они у вас есть), а так же макросы и глобальные переменные (которые сочтёте нужными)
    • Обеспечить программе вменяемый --help (на двух языках!) и man (на одном)

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

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

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

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

LecturesCMC/LinuxApplicationDevelopment2022/12_Documenting (последним исправлял пользователь FrBrGeorge 2022-12-06 17:48:19)