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

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

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

Doxygen

Cайт

Пример:

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

Sphinx

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

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

Man и --help

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

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

Д/З

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

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

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

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

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

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

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

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

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

LecturesCMC/LinuxApplicationDevelopment2020/10_Documenting (последним исправлял пользователь FrBrGeorge 2020-11-30 14:05:34)