Альтернативы для замены Doxygen

Я лично считаю, что этот подход прост, потому что документация о членах и классах действительно близка к коду, в то время как обзорные страницы очень легко редактировать в Wiki а также легко добавлять изображения, таблицы, Веб-браузер позволяет вам видеть обе документации. Мой коллега теперь предлагает поместить все в Doxygen, потому что мы можем создать один большой файл справки со всем в нем используя либо Microsoft WorkShop Microsoft, либо Qt Assistant. Меня беспокоит то, что редактирование документации в стиле Doxygen намного сложнее по сравнению с Wiki , особенно если вы хотите добавить таблицы, изображения,

Разработка ПО. Sphinx - это инструмент, который упрощает создание интеллектуальной и красивой документации, написанной Георгом Брандлом и лицензированной по лицензии BSD. Swagger - инструмент для документирования RESTapi с открытым исходным кодом. Это поможет вам создать великолепную документацию в дружественном для разработчиков способом. Бесплатная Открытый код Self-Hosted. Генератор документации PHP, основанный на анализе docblock.

Doxygen — первый по-настоящему успешный проект по Альтернатива. Предлагается заменить один инструмент конвейером. Рассматриваемая система Doxygen как раз и выполняет эту задачу: она .. оформить документацию (альтернативой могут быть, например, .. закопать пациента, но, увы, какой-то нормальной замены ему нет. Мое личное предпочтение состоит в том, чтобы иметь как Doxygen, так и управление версиями, глобальный поиск, глобальный поиск & заменить.

Альтернативы для замены Slate API Docs Generator

Войдите , пожалуйста. Хабр Geektimes Тостер Мой круг Фрилансим. Войти Регистрация. В этой статье мы сначала познакомимся с самой системой и её возможностями, затем разберёмся с её установкой и базовыми принципами работы, и, наконец, завершим знакомство рассмотрением различных примеров документации, примеров того, как следует документировать те или иные части кода. Словом, познакомимся со всем тем, что позволит вам освоиться и начать работать с этой замечательной системой. Введение Вероятнее всего, каждый из нас сталкивался с результатами работы различных генераторов документации. Общий принцип их работы следующий: на вход такого генератора поступает специальным образом комментированный исходный код, а иногда и другие компоненты программы, а на выходе создаётся готовая документация для распространения и использования. Рассматриваемая система Doxygen как раз и выполняет эту задачу: она позволяет генерировать на основе исходного кода, содержащего комментарии специального вида, красивую и удобную документацию, содержащую в себе ссылки, диаграммы классов, вызовов и т. К слову, список проектов, использующих Doxygen имеется на официальном сайте , причём большинство из этих проектов свободные. Поэтому желающие могут скачать исходник того или иного проекта и посмотреть как там разработчики осуществляли документацию. Установка и настройка Скачать последнюю версию Doxygen можно на официальном сайте , дистрибутивы которой доступны для большинства популярных операционных систем, кроме того, вы можете воспользоваться вашим пакетным менеджером. Помимо этого для комфортной и полнофункциональной работы рекомендуется установить Graphviz. Далее работа с Doxygen весьма тривиальна: достаточно запустить программу, указав ей путь к файлу с настройками. Дело в том, что каждому проекту соответствует свой файл настроек, в котором может быть прописан путь до исходников проекта, путь, по которому должна быть создана документация, а также большое число других разнообразных опций, которые подробно описаны в документации , и которые позволяют максимально настроить документацию проекта под свои нужды. В принципе, для редактирования данного файла и, вообще, работой с Doxygen, можно воспользоваться программой Doxywizard, которая чаще всего идёт вместе с Doxygen и которая позволяет чуть удобнее работать с файлом настроек слева — Doxywizard; справа — файл открытый в текстовом редакторе : Итак, приступим к созданию файла с настройками. Документация кода в Doxygen осуществляется при помощи документирующего блока.

Альтернатива Doxygen для С++

Под данным изречением-мемом, взятым с замечательной картинки Владимира Филонова , поставит свою подпись каждый человек, имеющий хотя бы отдалённое отношение к программированию. Весь вопрос, как? Как именно документировать-то? Сразу оговорюсь, что хотя проект создавался в первую очередь как альтернатива, а точнее, дополнение Doxygen для сишных и плюсовых API, архитектурно он в равной степени пригоден и для других языков. Это позволяет создавать порталы документации разноплановых библиотек — сами библиотеки могут быть написаны на разных языках, а в документации будет единство стиля во внешнем виде и поведении.

Несмотря на то, что этот традиционный способ всем понятен и по-прежнему широко используется, я глубоко убеждён что он в корне неверен. Дело в том, что он порождает документацию, которая всё время местами нерелевантна и отстаёт от объекта документации. Поддержка согласованности между созданными раздельно, а зачастую ещё и разными людьми, документацией и постоянно эволюционирующим API библиотеки — не эволюционируют только умершие или замороженные продукты! Специально обученный парсер пробегает по исходникам, вычленяет особым образом оформленные комментарии с документацией и строит структуру дерева публичных объявлений API.

Основным преимуществом данного подхода является гарантированная когерентность объявлений в исходниках API и в конечной документации. Даже при полном отсутствии в исходниках содержательных комментариев с собственно "документацией" , в конце мы будем иметь прекрасный снимок состояния API библиотеки, с возможностью "попрыгать" по объявлениям и описаниям типов, и т. Итак, с вашего позволения, я сконцентрируюсь на "правильном" подходе с автогенерацией. Какие варианты у нас имеются тут?

И с этими двумя тоже далеко не всё гладко. Doxygen — первый по-настоящему успешный проект по вытаскиванию комментариев из кода на плюсах и превращению оных в HTML-документацию с гиперссылками, картинками графов наследования, вызовов и т. И всё это было бы замечательно, если бы не два "но":.

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

Но даже если умолчальный доксигеновский HTML и устраивает кого-то с визуальной точки зрения а серьёзно, есть такие, кому он и вправду нравится эстетически?

Это подводит нас ко второй, более фундаментальной проблеме Doxygen:. К сожалению, если требуется что-то не по умолчанию , то QDoc страдает всё той же врождённой деревянностью , что и Doxygen растущей, понятно, из той же самой ж И при этом, — что уж совсем ни в какие ворота, — не умеет генерировать PDF! Doxygen умеет вытаскивать документацию из исходников и класть её вместе с деревом объявлений в XML базу данных.

Это будет нашим front-end. Ещё легче ответить на вопрос о том, что использовать в качестве back-end — конечно, Sphinx.

Sphinx заслуженно получил колоссальное распространение как инструмент написания технической документации. Но что самое главное, он полностью настраиваем с помощью Python-скриптов, причём их можно применять как для тюнинга внешнего вида, так и для расширения входного языка каковым для Sphinx является reStructuredText — а именно, дописывать свои директивы и потом использовать их в документации.

Замечу, что я не первый, кто пытался построить мост между Doxygen и Sphinx. Относительную известность приобрёл проект breathe , написанный на Python как расширение для Sphinx. В настоящий момент проект не слишком активно ковыряется отвёрточкой, и, увы, из коробки не пригоден для серьёзных задач.

Архитектурно он устроен следующим образом: он парсит XML-выхлоп доксигена и создаёт узлы reStructuredText дерева в памяти напрямую. Я же решил пойти несколько другим путём. Doxyrest — так называется наш мост — парсит доксигеновские.

Шаблонизатор генерирует файлы с reStructuredText , и уже эти. Основная фишка — конечно же, использование шаблонизатора. Но главное — подход с шаблонизатором позволяет применять Doxyrest для абсолютного большинства любых других языков , и в частности, разнообразных DSL — для которых никто и никогда не будет делать специализированных систем документации. Doxygen не умеет парсить ваш язык? Ваш язык теперь можно документировать с помощью Doxygen-комментариев и получать на выходе красивую Sphinx-документацию.

В настоящий момент для шаблонизации используется язык Lua просто потому что у меня уже была готовая и отлаженная библиотечка Lua string templates , но в теории ничто не мешает добавить поддержку и других языков шаблонизации.

Лучше один раз увидеть, чем сто раз услышать. Посему, вместо заключения я решил просто привести ссылки на результат работы Doxyrest в применении к различным языкам:. Несмотря на незаконченность содержательной части документации по ссылкам выше собственно описания классов, функций и т.

Смотрите, пробуйте, присоединяйтесь к разработке. А я с удовольствием отвечу на все вопросы в комментариях. А мне кажется, визуальные акценты помогают-таки при просматривании статей по диагонали. Вопрос количества и баланса, конечно, открытый и во многом субъективный.

Но вообще я за акценты. Впрочем, если у вас пример красивой документации, полученной таким методом — кидайте, можно будет обсудить более предметно. Затем что если хочется документацию иметь красивую, со сложной связностью и легко расширяемую, то лучше сразу писать доки на Sphinx. А так получается что вы хотите лоск Sphinx и сразу же загоняете себя в рамки Doxygen. Для себя выбрал другой путь — все документирование на Sphinx для любых исходников, а сбор документации через плагин Sphinx, который построен на механизме autodoc.

Вот мой sphinxcontrib-autoanysrc и есть еще куча аналогов. Так что используя простейший язык шаблонов можно в какой-то мере влиять на генерируемый результат. Выходные форматы как и у Doxygen — markdown, html, xml, man, latex.

Им бы взять Lua или Python — и то, и другое легко встраивается в плюсовые приложения. Потом, сама идея с опциональностью шаблонов наводит на мысль, что шаблоны эти планируется использовать лишь как дополнение к автосгенерированному дереву объявлений, на внешний вид которого можно повлиять только настроечными переменными — как и в Doxygen.

Вполне возможно, я что-то упсутил, но у них, увы, нет примеров использования этих шаблонов — в репозитории только плюсы, bash и cmake.. Вся цепочка рассуждений исходит из неверных предположений, что заказчик знает, чего хочет, а с задачей можно полностью разобраться до начала работ.

Совершенно верно — как средство разбора и вытаскивания документирующих комментариев он пока не имеет равных. Кроме того, когда допилится интеграция с Clang а то сейчас она какая-то уж слишком экспериментальная , этих самых равных и искать никакого смысла не будет. А сделать красивый вывод по информации, полученной Доксигеном — в этом и есть вся соль предлагаемого мной проекта.

Доксиген умеет доставать информацию из исходников. Sphinx умеет генерировать красивый — и, что главное, настраиваемый, — HTML.

Doxyrest — мост между этими двумя товарищами. Всё правильно. А в случае с использованием Doxyrest, отдельные страницы с абстрактным описанием — это будут просто. Ну я собственно и не противопоставлял — просто сказал, что и с Doxyrest тоже можно создавать самостоятельные страницы с документацией как обычные. И конечно, и с Doxygen, и с Doxyrest из этих самостоятельных страниц можно ссылаться на авто-сгенерированные страницы API.

Другое дело что Doxyrest перекладывает всю работу по созданию финальной красивой HTML страницы на инструмент, который прекрасно с этим справляется значительно лучше, чем Doxygen. Вот и всё. Я уже писал выше — при авто-генерации документации имеется гарантия релевантности всех объявлений. Вы можете побегать по API, посмотреть какие аргументы принимаются, что возвращается, какие есть поля и т. Бестолковость абсолютного большинства примеров Доксигеновской документации, действительно имеет место быть.

Но это проблема конкретного контента , а не подхода, согласитесь? Можно ведь взять и написать толковую документацию, а не просто: open открывает, get возвращает. Но у меня есть смелая теория, почему сейчас всё обстоит именно так. Разработчики не хотят тратить усилия на написание толковых комментариев, потому что — барабанная дробь — конечная Доксигеновская документация всё равно будет выглядеть как говно!

Даже в тех редких случаях, когда разработчики и рады были бы написать нечто толковое в документации, их останавливает то, что… и дальше по тексту ;. Войдите , пожалуйста. Хабр Geektimes Тостер Мой круг Фрилансим.

Войти Регистрация. Мотивация По большому счёту, подходов к документированию API и библиотек — плюсовых или нет — ровно два. Первый, это писать всё ручками. Второй, "правильный" подход, состоит в том, чтобы генерировать документацию по исходникам автоматически.

И всё это было бы замечательно, если бы не два "но": Стандартный генерируемый доксигеном HTML, как бы это помягче сказать… не обременён элегантностью. Это подводит нас ко второй, более фундаментальной проблеме Doxygen: Doxygen за свою долгую жизнь так и не отрастил настоящую, модульную настраиваемость.

Альтернатива Предлагается заменить один инструмент конвейером. Что оставляем старого? This is a detailed documentation for class Foo. Будем писать документацию так же, как и раньше! Осталось подружить Doxygen и Sphinx. Строим мост Замечу, что я не первый, кто пытался построить мост между Doxygen и Sphinx.

Эта шляпа совсем не шляпа, а Red Hat OpenShift. Го в Docker. Читают сейчас. Как передать данные между микроконтроллерами на Mbps 16,5k Поделиться публикацией. Похожие публикации. Eltex Новосибирск.

Альтернативы для замены Doxygen

Чистый, интуитивно понятный дизайн. С Slate описание вашего API находится в левой части документации, и все примеры кода находятся на правой стороне. Шифер чувствителен, поэтому он отлично смотрится на планшетах, телефонах и даже в печати. Все на одной странице - Прошли те дни, когда вашим пользователям приходилось искать через миллион страниц, чтобы найти то, что они хотели. Slate помещает всю документацию на одну страницу. Однако мы не пожертвовали связностью.

Где разместить кодовую документацию?

Кто работал с питоновским Sphinx? Какие ему есть альтернативы? В Sphinx не устраивает очень неудобная работа с оглавлением. Пробовал использовать его как десктопную вики. Главное чтоб была удобна. Исходя из большого списка проектов, которые используют сфинкс а значит и хороших песпектив его развития , успешные альтернативы будут включать только непосредственно написание документации в необходимых форматах. Поскольку не все форматы необходимы, то можно ограничиться LaTeX и man и поступиться документацией html, потому что её, как мне кажется, делать сложнее. Это для инструкций по использованию. А для описания файлов, модулей, классов, пространств имен используется doxygen. RU Регистрация - Вход.

Doxygen 1. Я знаю, что это не альтернатива, но это такие большие новости, которые я хотел бы выделить из комментариев. Ваш лучший выбор - настроить настройки Doxygen:. Я просто скопировал вставку самых интересных функций, которые он предлагает:. Он использует reStructuredText в качестве языка разметки.

Мое личное предпочтение состоит в том, чтобы иметь как Doxygen, так и управление версиями, глобальный поиск, глобальный поиск & заменить. Какие ему есть альтернативы? В Sphinx не А для описания файлов, модулей, классов, пространств имен используется doxygen. Doxygen имеет встроенную поддержку генерации документации в формате HTML, LaTeX, man, RTF и XML. Также вывод может быть.

Поиск в Google для roxygen2 и doxygen в первую очередь приводит к тому, что roxygen аналогичен результатам для doxygen. Я нашел несколько пакетов с Doxy-файлами, но без согласованной организации. Существует также Doxy-файл в корневом каталоге Matrix но в предыдущих выпусках был in inst. Эта документация также экспортируется за пределы каталога пакета.

Под данным изречением-мемом, взятым с замечательной картинки Владимира Филонова , поставит свою подпись каждый человек, имеющий хотя бы отдалённое отношение к программированию. Весь вопрос, как? Как именно документировать-то? Сразу оговорюсь, что хотя проект создавался в первую очередь как альтернатива, а точнее, дополнение Doxygen для сишных и плюсовых API, архитектурно он в равной степени пригоден и для других языков. Это позволяет создавать порталы документации разноплановых библиотек — сами библиотеки могут быть написаны на разных языках, а в документации будет единство стиля во внешнем виде и поведении.

Doxygen генерирует документацию на основе набора исходных текстов и также может быть настроен для извлечения структуры программы из недокументированных исходных кодов. Возможно составление графов зависимостей программных объектов, диаграмм классов и исходных кодов с гиперссылками. Doxygen - консольная программа в духе классической Unix. Она работает подобно компилятору, анализируя исходные тексты и создавая документацию. Graphviz — это свободно распространяемый пакет утилит для визуализации данных. Нам он нужен для того, чтобы Doxygen мог показать в документации отношения наследования, графы вызовов и прочую информацию в виде наглядных изображений.

.

.

.

ВИДЕО ПО ТЕМЕ: How to Comment & Document Your Code Using Doxygen and Graphviz
Понравилась статья? Поделиться с друзьями:
Комментариев: 0
  1. Пока нет комментариев...

Добавить комментарий

Отправляя комментарий, вы даете согласие на сбор и обработку персональных данных