Оформлення документації в Doxygen



Нещодавно мною була написана стаття, присвячена системі документації Doxygen (якщо ви не знайомі з даною системою, то раджу звернути увагу на зазначену статтю і познайомитися з нею хоча б у загальних рисах). У коментарях до неї було піднято важливе питання про оформлення документації в Doxygen, і це питання актуальне, оскільки часто використовується стандартне оформлення, яке хоч і практичне, але досить непоказне.

У даній статті я відповім на це питання. Для цього ми розглянемо загальні принципи оформлення документації Doxygen, познайомимося з ними, і подивимося на прикладах, чого можна домогтися, спираючись на них.

Налаштування зовнішнього вигляду документації

Спочатку розглянемо той, який функціонал надає Doxygen для налаштування оформлення (при цьому слід звернути увагу на те, що в основному описуються далі налаштування відносяться саме до генеруємому HTML-документа). Взагалі, цей розділ докладно описаний в офіційній документації, зазначу лише основні деталі в ньому і разбавлю його для ясності прикладами.

Налаштування оформлення
Іконка для проекту
Найпростіше, що можна налаштувати в оформленні — це іконку проекту. Для цього необхідно вказати у файлі налаштувань в опції PROJECT_LOGO шлях до іконки:
PROJECT_LOGO = <путь_к_иконке>

Колірна схема
Для того, щоб просто змінити колірну схему сторінки HTML використовуються наступні опції у файлі налаштувань:
Опція Значення
HTML_COLORSTYLE_HUE Вказує тон колірної схеми
HTML_COLORSTYLE_SAT Вказує яскравість кольорової схеми
HTML_COLORSTYLE_GAMMA Вказує гаму колірної схеми
Нижче представлені приклади одній і тій же документації з різними налаштуваннями колірної схеми:


Засоби навігації
Основними засоби навігації по документації в Doxygen є: меню з вкладками і ієрархічне дерево. Вони представлені нижче на скріншоті.


Для налаштування відображення цих елементів використовуються наступні опції у файлі налаштувань:
Опція Значення
DISABLE_INDEX Вимикає відображення меню з вкладками
GENERATE_TREEVIEW Показує відображати чи ні ієрархічне дерево
Динамічний вміст документації
Для того, щоб зробити HTML документацію більш інтерактивною, Doxygen надає ряд опцій, яке за замовчуванням:
Опція Значення
HTML_DYNAMIC_SECTIONS У разі встановлення цієї опції, Doxygen буде приховувати певні елементи HTML документації (наприклад, графи), які користувач за бажанням може розкрити згодом
INTERACTIVE_SVG У разі, якщо включено побудова графів за допомогою Graphviz і в якості формату побудови графів вказаний SVG, Doxygen буде створювати інтерактивні файли SVG, які можна збільшувати і переміщати
Заголовок, футер та каскадна таблиця стилів
Для налаштування шрифтів, кольорів, відступів та інших деталей оформлення HTML документації, можна змінити стандартну каскадну таблицю стилів. Крім того, Doxygen дозволяє змінювати заголовок і футер для кожної HTML сторінки, яку він генерує, наприклад, для того, щоб генерується документація збігалася з зовнішнім стилем решті частини вашого сайту.

Для того, щоб отримати відповідні файли для подальшого редагування, виконайте команду:
doxygen-w html header.html footer.html customdoxygen.css 

Вона створить три файлу:
  1. header.html представляє собою HTML-фрагмент, який використовує Doxygen для початку HTML сторінки. Зверніть увагу, що даний фрагмент містить пару спеціальних команд, які починаються зі знака долара: вони будуть автоматично замінені при створенні документації;
  2. footer.html представляє собою HTML-фрагмент, який використовує Doxygen для завершення HTML сторінки. Тут також можуть зустрічатися спеціальні команди, про які було згадано раніше;
  3. customdoxygen.css представляє собою використовувану за замовчуванням каскадну таблицю стилів. Рекомендується тільки подивитися на цій файл і змінити певні параметри шляхом їх розміщення в окремому файлі.
Після того, як ви відредагуєте ці файли, необхідно вказати Doxygen, щоб він їх використовував при побудові документації, замість стандартних файлів. Робиться це за допомогою наступних команд:
Опція Значення
HTML_HEADER Вказує шлях до користувача HTML-файлу, який описує заголовок (у наведеному вище прикладі це шлях до header.html)
HTML_FOOTER Вказує шлях до користувача HTML-файлу, який описує футер(у наведеному вище прикладі це шлях до footer.html)
HTML_EXTRA_STYLESHEET Вказує шлях до каскадної таблиці стилів. Зверніть увагу на те, що вона буде використовуватися поряд зі стандартною таблицею стилів і тому у неї досить описувати тільки те, що ви змінили
Приклад зміни оформлення
Далі ми розглянемо гарні приклади різних стилів і оформлювальний рішень, але поки просто покажемо для впевненості у власних силах, як можна змінювати стиль.

Давайте зробимо для прикладу заголовок документації жирним і змінимо його кольору, для цього створимо таблицю стилів style.css з наступним вмістом (projectname — це id блоку з ім'ям проекту, переконатися в цьому можна відкривши файл header.html:
#projectname {
color: #3B5588;
font-weight: bold;
}

Після цього в файлі налаштувань в опції HTML_EXTRA_STYLESHEET вкажемо шлях до створеного файлу і створимо документацію. Результат буде мати наступний вигляд (для порівняння показується і попередній варіант):


Точно так само можна змінити стиль всього іншого, так що дерзайте!

Параметри структури документації

Раніше ми розглядали те, як можна змінити зовнішній вигляд документації, однак його зміна не вплине на структуру документації, для її зміни чи існує інший підхід.

Для цього використовується спеціальний файл, що описує структуру документа за допомогою мови розмітки XML. Doxygen потім використовує його для визначення яку інформацію необхідно відображати, в якому порядку, а також частково про те, як її відобразити.

Аналогічно, як і при зміні оформленні документації, для початку необхідно отримати використовуваний за замовчуванням такий файл. Для цього використовується команда l (від layout):
doxygen-l [ім'я_файлу]

Верхній рівень даного файлу має наступний вигляд:
<doxygenlayout version="1.0">
<navindex>
...
</navindex>
<class>
...
</class>
<namespace>
...
</namespace>
<file>
...
</file>
<group>
...
</group>
<fs>
...
</directory>
</doxygenlayout>

Подробиці роботи з цією структурою описані в відповідному розділі офіційній документації.

Відзначимо лише те, що після того, як ви створили свій файл, необхідно змінити у файлі налаштувань опцію LAYOUT_FILE, вказавши в ній шлях до даного файлу:
LAYOUT_FILE = <шлях_до_файлу>

Приклад зміни структури
Знову ж для того, щоб отримати впевненість у своїх можливостях, зробимо невелику зміну в даній структурі.

В першу чергу згенеруємо файл зі структурою (як було зроблено вище), а тепер додамо нову вкладку в меню.

При додаванні нової вкладки необхідно вказати їй тип user. В даному випадку, ми додамо вкладку, яка буде посилатися на певний сайт, наприклад, на habrahabr.ru для цього знайдемо розділ navindex і додамо в його кінець відповідну вкладку:
<navindex>
...
<tab type="user" url="http://www.habrahabr.ua" title="Хабрахабр"/> 
</navindex>

Результат буде виглядати наступним чином:


Приклади оформлення документації

Після того, як ми розібралися з тим, як можна налаштувати оформлення документації, прийшла пора подивитися вже готові приклади, які можна використовувати для своїх проектів.

Qt4 тема
Нижче представлений зразок документації створеної на основі теми, що копіювала документацію Qt четвертої версії.


Bootstrap тема
Спеціально для шанувальників Bootstrap була створена відповідна тема.


Ще два приклади
наступного посилання можна ознайомитися та завантажити відразу дві теми для оформлення документації.



Висновок

Підводячи підсумок, хотілося б відзначити, що досить складно було знайти готові теми для документації, однак насправді функціонал, який надає Doxygen для налаштування оформлення, дуже широкий і дозволяє легко налаштувати документацію під ваш смак, тож буду сподіватися, що ця стаття допоможе вам зробити вашу документацію красивіше і приємніше для читача.

Спасибі за увагу!

Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.