Я настраиваю генератор документации для внутренней цели, которая генерирует HTML-документацию для классов и методов C++. Есть ли какой-нибудь пример хорошего дизайна документации HTML? MSDN (например, this) выглядит немного устаревшим, то же самое - результаты doxygen/javadoc/sphinx. Кто-нибудь видел документацию, которая выглядит ДЕЙСТВИТЕЛЬНО хорошей?хороший пример оформления документации на C++?
ответ
Посмотрите документацию по библиотекам Boost, например, документацию библиотеки Math. Я не знаю, как это происходит, но я не удивлюсь, если это doxygen. Doxygen на самом деле является стандартом для документации на C++. Он очень гибкий, и вы можете легко использовать CSS для настройки внешнего вида.
Я считаю, что «хороший дизайн документации HTML» - очень субъективная тема. Я нахожу doxygen сгенерированные документы очень полезными и чистыми . И это функция, которую я больше всего ценю, когда речь заходит о документации.
Однако я нахожу документы для Android (см. reference doc или dev guide) и полезными и красиво выглядящими (хотя это и для Java).
Другими красиво выглядящими документами, которые я использую, являются: Qt docs - c++ и Dojo - js.
спасибо. Пользовательский интерфейс точно задал этот вопрос, чтобы увидеть субъективные повторы. Мне потребуется несколько часов для примеров документов Google, но у многих уже есть закладки для документации, которые, по их мнению, являются «супер» :). – grigoryvp
Обратите внимание, что именно система документации Qt вдохновила создание Doxygen в первую очередь. Согласно Doxygen часто задаваемые вопросы, Qt не выпускает свои инструменты, поэтому Дмитрий пошел и написал свой собственный. – RBerteig
Я думаю, что Doxygen, вероятно, является стандартом для документации на C++. Многочисленные форматы вывода (HTML, Latex, PDF и т. Д.) - отличная возможность.
GTKmm documentation - отличный пример того, что возможно с Doxygen. Я думаю, что они используют диаграммы наследования, но вы также можете создавать диаграммы сотрудничества и диаграммы использования файлов (file1.h включает file2.h и т. Д.).
Мне очень нравится allegro.cc documentation для библиотеки программирования игр Allegro.
Вот хороший пример page, который показывает некоторые из особенностей:
- «Связанные дискуссии» интегрирует с форумами www.allegro.cc в (автоматически захватывает релевантные результаты поиска)
- «Связанные проекты» интегрирует с списками проектов www.allegro.cc (проекты, которые используют это ключевое слово)
- С эстетической точки зрения дизайн очень чистый и простой.
+1 для того, чтобы подчеркнуть, что doxygen может использовать пользовательские стили, шаблоны и конфигурации. – RBerteig
Я думаю, что boost использует что-то, называемое quickbooks для документации. я не уверен на 100%, это то, что я помню из разговора по рассылке. – gred