Инструменты для генерирования документации из кода

При подходе Docs as code документацию создают на определенном языке разметки, например, Markdown, и редактируют в репозиториях GitHub или GitLab. Не всем пользователям будет понятен подобный формат, поэтому для получения удобочитаемого документа необходимо обращаться к инструментам для генерирования документации из кода. Какие существуют инструменты и в чем их особенность?

Для начала следует рассмотреть понятие «генерирование документации из кода». Это процесс извлечения информации, содержащейся в исходном коде и настройках документируемого ПО, для дальнейшего использования в удобном формате.
К исходным данным рассматриваемого процесса относится исходный код, а к выходным – документация или ее фрагмент. Процесс генерирования документов из кода состоит из нескольких этапов:

• изменение исходного кода в структурированный формат. Чаще всего обращаются к XML или JSON/YAML;
• преобразование полученного структурированного формата в необходимый формат документации. При этом используются такие языки разметки, как Markdown, Asciidoc, reStructuredText и др.;
• получение готовой документации в форматах pdf, html, odt или docx.

• Sphinx,
• Doxygen,
• Swagger,
• Pandoc,
• Dr. Explain,
• Ghostdoc,
• Natural Docs,
• Phpdocumentator и др.

Каждый из перечисленных инструментов поддерживает определенные языки программирования. Различными у каждого инструмента могут быть форматы вывода информации. Рассмотрим три наиболее популярных инструмента.

Sphinx был разработан для проекта Python. Первый релиз Sphinx состоялся в 2008 году. Sphinx позволяет создавать документы в текстовом виде, а также преобразовывать их в разные форматы. Инструмент удобно применять к версиям в системах управления отслеживания изменений (Git). Доступ к инструменту осуществляется согласно лицензии BSD. Sphinx поддерживает следующие языки: C, C++, PHP, Python, Ruby, JavaScript. При генерировании документации из кода в данном случае доступны следующие выходные форматы: HTML, CHM, LaTex, Man pages, ePub.

Генерировать документ из исходного кода можно при помощи инструмента под названием Doxygen. Инструмент также позволяет осуществлять статический анализ исходного кода. Первый выпуск данной программы состоялся в 1997 году, автором стал Димитри ван Хееш. Основу для документирования составляет язык C++, но поддерживаются и другие (C, Java, C#, PHP, Python, Fortran, IDL, Objective-C, VHDL). Выходными данными при использовании этого генератора будут CHM, HTML, RTF, LaTex, Doc book, XML, Man pages. Doxygen поддерживается практически на всех Unix-подобных системах. Инструмент использует такие проекты, как Mozilla, Crystal Space, KDE.

Swagger представляет собой программу для описания и документирования REST API. При помощи данного инструмента можно также генерировать документацию для пользователей. Инструмент создан в 2011 году Тони Тэмом. Swagger поддерживает следующие языки: Java, C++, C#, Kotlin, Skala, Haskell, PHP, Python. Выходными данными при использовании этого генератора будут HTML и Confluence. Данный инструмент предлагает автоматически генерировать документацию из кода или написать ее самостоятельно.

Первый способ гораздо проще, но документация может быть некорректной и нечитабельной. Для использования второго подхода необходимо знать синтаксис Swagger (можно обращаться к JSON/YAML). Помощником в данном случае станет Swagger Editor. Во втором случае документации получится более качественной и будут учтены особенности конкретного проекта.

При выборе генератора документации из кода необходимо учитывать навыки и знания специалиста, который будет генерировать документы; язык программирования, на котором написан исходный код; необходимый формат будущей документации. На основе перечисленных данных можно выбрать тот или иной инструмент.