Doxygen theme

A mod­ern, mo­bile-friend­ly drop-in re­place­ment for the stock Doxy­gen HTML out­put, with a first-class search func­tion­al­i­ty. Gen­er­at­ed from Doxy­gen-pro­duced XML files, file­names and URLs are ful­ly com­pat­i­ble with the stock out­put to avoid bro­ken links once you switch.

Ba­sic us­age

The base is con­tained in a sin­gle Python script and re­lat­ed style/tem­plate files, for ad­vanced fea­tures such as math ren­der­ing it’ll make use of in­ter­nals of some m.css plug­ins. Clone the m.css GitHub re­pos­i­to­ry and look in­to the doxygen/ di­rec­to­ry:

git clone git://github.com/mosra/m.css
cd m.css/doxygen

The script re­quires Python 3.6, de­pends on Jin­ja2 for tem­plat­ing and Pyg­ments for code block high­light­ing. You can in­stall the de­pen­den­cies via pip or your dis­tri­bu­tion pack­age man­ag­er:

# You may need sudo here
pip3 install jinja2 Pygments

If your doc­u­men­ta­tion in­cludes math for­mu­las, in ad­di­tion you need some La­TeX dis­tri­bu­tion in­stalled. Use your dis­tri­bu­tion pack­age man­ag­er, for ex­am­ple on Ubun­tu:

sudo apt-get install texlive-base texlive-latex-extra texlive-fonts-extra

Now, in or­der to pre­serve your orig­i­nal Doxy­gen con­fig­u­ra­tion, cre­ate a new Doxyfile-mcss file next to your orig­i­nal Doxyfile and put the fol­low­ing in­side:

@INCLUDE                = Doxyfile
GENERATE_HTML           = NO
GENERATE_XML            = YES
XML_PROGRAMLISTING      = NO

This will de­rive the con­fig­u­ra­tion from the orig­i­nal Doxyfile, dis­ables builtin Doxy­gen HTML out­put and en­ables XML out­put in­stead, with some un­need­ed fea­tures dis­abled for faster pro­cess­ing. Now run dox2html5.py and point it to your Doxyfile-mcss:

./dox2html5.py path/to/your/Doxyfile-mcss

It will run doxygen to gen­er­ate the XML out­put, pro­cess­es it and gen­er­ates the HTML out­put in the con­fig­ured out­put di­rec­to­ry. Af­ter the script is done, just open gen­er­at­ed index.html to see the re­sult.

If you see some­thing un­ex­pect­ed or not see some­thing ex­pect­ed, check the Trou­bleshoot­ing sec­tion be­low.

Fea­tures

  • Mod­ern, valid, mo­bile-friend­ly HTM­L5 markup with­out ta­ble lay­outs
  • Min­i­mal­is­tic de­sign with­out un­nec­es­sary chrome and UI el­e­ments
  • URLs ful­ly com­pat­i­ble with stock Doxy­gen HTML out­put to pre­serve ex­ist­ing links
  • Fo­cused on pre­sent­ing the ac­tu­al writ­ten doc­u­men­ta­tion while re­duc­ing ques­tion­able au­to-gen­er­at­ed con­tent
  • Math ren­dered as em­bed­ded SVG in­stead of raster im­ages / Math­Jax. The sup­port­ed fea­ture set is equiv­a­lent to the m.math Pel­i­can plug­in, see its doc­u­men­ta­tion for more in­for­ma­tion.
  • Graphviz / Dot di­a­grams ren­dered as em­bed­ded SVG. The sup­port­ed fea­ture set is equiv­a­lent to the m.dot Pel­i­can plug­in, see its doc­u­men­ta­tion for more in­for­ma­tion.
  • Us­es Pyg­ments for bet­ter code high­light­ing. The sup­port­ed fea­ture set is equiv­a­lent to the m.code Pel­i­can plug­in, see its doc­u­men­ta­tion for more in­for­ma­tion.

Im­por­tant dif­fer­ences to stock HTML out­put

  • Vast­ly im­proved search ca­pa­bil­i­ties with im­me­di­ate feed­back
  • De­tailed de­scrip­tion is put first and fore­most on a page, be­fore the mem­ber list­ing
  • Files, di­rec­to­ries and sym­bols that don’t have any doc­u­men­ta­tion are not present in the out­put at all. This is done in or­der to en­cour­age good doc­u­men­ta­tion prac­tices — hav­ing the out­put con­sist of an ac­tu­al hu­man-writ­ten doc­u­men­ta­tion in­stead of just au­to­gen­er­at­ed lists.
  • Ta­ble of con­tents is gen­er­at­ed for com­pound ref­er­ences as well, con­tain­ing all sec­tions of de­tailed de­scrip­tion to­geth­er with an­chors to mem­ber list­ings
  • Pri­vate mem­bers and anony­mous names­paces are al­ways ig­nored, how­ev­er pri­vate vir­tu­al func­tions are list­ed in case they are doc­u­ment­ed (why?)
  • In­ner class­es are list­ed in the pub­lic/pro­tect­ed type sec­tions in­stead of be­ing list­ed in a sep­a­rate sec­tion ig­nor­ing their pub­lic/pri­vate sta­tus
  • Class ref­er­ences con­tain al­so their tem­plate spec­i­fi­ca­tion on the linked page
  • Func­tion sig­na­tures don’t con­tain constexpr and noexcept any­more. These key­words are in­stead added as flags to the func­tion de­scrip­tion to­geth­er with virtualness and explicitity. On the oth­er hand, im­por­tant prop­er­ties like static, const and r-val­ue over­loads are part of func­tion sig­na­ture.
  • For bet­ter vis­ual align­ment, func­tion list­ing is done us­ing the C++11 trail­ing re­turn type (auto in front) and type­def list­ing is done with using). How­ev­er, the de­tailed doc­u­men­ta­tion is kept in the orig­i­nal form.
  • Func­tion and macro pa­ram­e­ters and enum val­ues are ver­ti­cal­ly aligned in the mem­ber list­ing for bet­ter read­abil­i­ty
  • De­fault class tem­plate pa­ram­e­ters are not need­less­ly re­peat­ed in each mem­ber de­tailed docs
  • Dep­re­ca­tion mark­ers are prop­a­gat­ed to mem­ber and com­pound list­ing pages and search re­sults; deleted func­tions are marked in search as well

In­ten­tion­al­ly un­sup­port­ed fea­tures

Fea­tures that I don’t see a point in be­cause they just ar­tif­i­cal­ly in­flate the amount of gen­er­at­ed con­tent for no added val­ue.

  • Class hi­er­ar­chy graphs are ig­nored (it on­ly in­flates the doc­u­men­ta­tion with lit­tle added val­ue)
  • Al­pha­bet­i­cal list of sym­bols and al­pha­bet­i­cal list of all mem­bers of a class is not cre­at­ed (the API should be or­ga­nized in a way that makes this un­nec­es­sary, there’s al­so search for this)
  • Ver­ba­tim list­ing of parsed head­ers, “In­cludes” and “In­clud­ed By” lists are not present (use your IDE or GitHub in­stead)
  • Ini­tial­iz­ers of de­fines and vari­ables are un­con­di­tion­al­ly ig­nored (one can al­ways look in the sources, if re­al­ly need­ed)
  • No sec­tion with list of ex­am­ples or link­ing from func­tion/class doc­u­men­ta­tion to re­lat­ed ex­am­ple code (he ex­am­ple code should be ac­com­pa­nied with cor­re­spond­ing tu­to­ri­al page in­stead)
  • inline func­tions are not marked as such (I see it as an unim­por­tant im­ple­men­ta­tion de­tail)
  • The CREATE_SUBDIRS Doxy­file op­tion is not sup­port­ed. This op­tion caus­es Doxy­gen to scat­ter the XML files across nu­mer­ous sub­di­rec­to­ries to work around lim­its of an­cient filesys­tems. Im­ple­ment­ing sup­port for this op­tion would be too much ef­fort for too lit­tle gain and so m.css sim­ply aborts if it dis­cov­ers this op­tion be­ing en­abled. Set it back to NO it in your Doxyfile-mcss over­ride.

Not yet im­ple­ment­ed fea­tures

  • Click­able sym­bols in code snip­pets. Doxy­gen has quite a lot of false pos­i­tives while a lot of sym­bols stay un­matched. I need to find a way around that.
  • Doc­u­ment­ed friend class­es, structs and unions. Doxy­gen is un­able to cross-link the dec­la­ra­tions with the def­i­ni­tions.
  • Prop­er scop­ing for friend and re­lat­ed func­tions/class­es/vari­ables etc. Doxy­gen doesn’t pro­vide any names­pace scop­ing for these and at the mo­ment I have no way to deduct that in­for­ma­tion.

Con­fig­u­ra­tion

The script takes most of the con­fig­u­ra­tion from the Doxyfile it­self, (ab)us­ing the fol­low­ing builtin op­tions:

Vari­able De­scrip­tion
@INCLUDE In­cludes in Doxyfiles are sup­port­ed
PROJECT_NAME Ren­dered in top navbar, foot­er fine print and page ti­tle
PROJECT_BRIEF If set, ap­pend­ed in a thin­ner font to PROJECT_NAME
OUTPUT_DIRECTORY Used to dis­cov­er where Doxy­gen gen­er­ates the files
XML_OUTPUT Used to dis­cov­er where Doxy­gen puts the gen­er­at­ed XML
HTML_OUTPUT The out­put will be writ­ten here
TAGFILES Used to dis­cov­er what base URL to prepend to ex­ter­nal ref­er­ences
HTML_EXTRA_STYLESHEET List of CSS files to in­clude. Rel­a­tive paths are searched rel­a­tive to the Doxy­file base dir and to the dox2html5.py script dir as a fall­back. See Theme se­lec­tion for more in­for­ma­tion.
HTML_EXTRA_FILES List of ex­tra files to copy (for ex­am­ple ad­di­tion­al CSS files that are @imported from the pri­ma­ry one). Rel­a­tive paths are searched rel­a­tive to the Doxy­file base dir and to the dox2html5.py script dir as a fall­back.
DOT_FONTNAME Font name to use for @dot and @dotfile com­mands. To en­sure con­sis­tent look with the de­fault m.css themes, set it to Source Sans Pro. Doxy­gen de­fault is Helvetica.
DOT_FONTSIZE Font size to use for @dot and @dotfile com­mands. To en­sure con­sis­tent look with the de­fault m.css themes, set it to 16. Doxy­gen de­fault is 10.

In ad­di­tion, the m.css Doxy­gen theme rec­og­nizes the fol­low­ing ex­tra op­tions:

Vari­able De­scrip­tion
M_THEME_COLOR Col­or for <meta name="theme-color" />, cor­re­spond­ing to the CSS style. If emp­ty, no <meta> tag is ren­dered. See Theme se­lec­tion for more in­for­ma­tion.
M_FAVICON Fav­i­con URL, used to pop­u­late <link rel="icon" />. If emp­ty, no <link> tag is ren­dered. Rel­a­tive paths are searched rel­a­tive to the Doxy­file base dir and to the dox2html5.py script dir as a fall­back. See Theme se­lec­tion for more in­for­ma­tion.
M_LINKS_NAVBAR1 Left navbar col­umn links. See Navbar links for more in­for­ma­tion.
M_LINKS_NAVBAR2 Right navbar col­umn links. See Navbar links for more in­for­ma­tion.
M_MAIN_PROJECT_URL If set and PROJECT_BRIEF is al­so set, then PROJECT_NAME in the top navbar will link to this URL and PROJECT_BRIEF in­to the doc­u­men­ta­tion main page, sim­i­lar­ly as shown here.
M_HTML_HEADER HTML code to put at the end of the <head> el­e­ment. Use­ful for link­ing ar­bi­trary JavaScript code or, for ex­am­ple, adding <link> CSS stylesheets with ad­di­tion­al prop­er­ties and IDs that are oth­er­wise not pos­si­ble with just HTML_EXTRA_STYLESHEET
M_PAGE_HEADER HTML code to put at the top of ev­ery page. Use­ful for ex­am­ple to link to dif­fer­ent ver­sions of the same doc­u­men­ta­tion. The {filename} place­hold­er is re­placed with cur­rent file name.
M_PAGE_FINE_PRINT HTML code to put in­to the foot­er. If not set, a de­fault gener­ic text is used. If emp­ty, no foot­er is ren­dered at all. The {doxygen_version} place­hold­er is re­placed with Doxy­gen ver­sion that gen­er­at­ed the in­put XML files.
M_CLASS_TREE_EXPAND_LEVELS How many lev­els of the class tree to ex­pand. 0 means on­ly the top-lev­el sym­bols are shown. If not set, 1 is used.
M_FILE_TREE_EXPAND_LEVELS How many lev­els of the file tree to ex­pand. 0 means on­ly the top-lev­el dirs/files are shown. If not set, 1 is used.
M_EXPAND_INNER_TYPES Whether to ex­pand in­ner types (e.g. a class in­side a class) in the sym­bol tree. If not set, NO is used.
M_MATH_CACHE_FILE File to cache ren­dered math for­mu­las. If not set, m.math.cache file in the out­put di­rec­to­ry is used. Old cached out­put is pe­ri­od­i­cal­ly pruned and new for­mu­las added to the file. Set it emp­ty to dis­able caching.
M_SEARCH_DISABLED Dis­able search func­tion­al­i­ty. If this op­tion is set, no search da­ta is com­piled and the ren­dered HTML does not con­tain any search-re­lat­ed UI or sup­port. If not set, NO is used.
M_SEARCH_DOWNLOAD_BINARY Down­load search da­ta as a bi­na­ry to save band­width and ini­tial pro­cess­ing time. If not set, NO is used. See Search for more in­for­ma­tion.
M_SEARCH_HELP HTML code to dis­play as help text on emp­ty search pop­up. If not set, a de­fault mes­sage is used. Has ef­fect on­ly if M_SEARCH_DISABLED is not YES.
M_SEARCH_EXTERNAL_URL URL for ex­ter­nal search. The {query} place­hold­er is re­placed with ur­len­cod­ed search string. If not set, no ex­ter­nal search is of­fered. See Search for more in­for­ma­tion. Has ef­fect on­ly if M_SEARCH_DISABLED is not YES.

Note that names­pace, di­rec­to­ry and page lists are al­ways ful­ly ex­pand­ed as these are not ex­pect­ed to be ex­ces­sive­ly large.

Theme se­lec­tion

By de­fault, the dark m.css theme to­geth­er with Doxy­gen-theme-spe­cif­ic ad­di­tions is used, which cor­re­sponds to the fol­low­ing con­fig­u­ra­tion:

HTML_EXTRA_STYLESHEET = \
    https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600 \
    ../css/m-dark+doxygen.compiled.css
M_THEME_COLOR = #22272e
M_FAVICON = favicon-dark.png

If you have a site al­ready us­ing the m-dark.compiled.css file, there’s an­oth­er file called m-dark.doxygen.compiled.css, which con­tains just the Doxy­gen-theme-spe­cif­ic ad­di­tions so you can re­use the al­ready cached m-dark.compiled.css file from your main site:

HTML_EXTRA_STYLESHEET = \
    https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600 \
    ../css/m-dark.compiled.css \
    ../css/m-dark.doxygen.compiled.css
M_THEME_COLOR = #22272e

If you pre­fer the light m.css theme in­stead, use the fol­low­ing con­fig­u­ra­tion (and, sim­i­lar­ly, you can use m-light.compiled.css to­geth­er with m-light.doxygen.compiled-css in place of m-light+doxygen.compiled.css:

HTML_EXTRA_STYLESHEET = \
    https://fonts.googleapis.com/css?family=Libre+Baskerville:400,400i,700,700i%7CSource+Code+Pro:400,400i,600 \
    ../css/m-light+doxygen.compiled.css
M_THEME_COLOR = #cb4b16
M_FAVICON = favicon-light.png

See the CSS files sec­tion be­low for more in­for­ma­tion about cus­tomiz­ing the CSS files.

Search op­tions

Sym­bol search is im­ple­ment­ed us­ing JavaScript Typed Ar­rays and does not need any serv­er-side func­tion­al­i­ty to per­form well — the client au­to­mat­i­cal­ly down­loads a tight­ly packed bi­na­ry con­tain­ing search da­ta and per­forms search di­rect­ly on it.

How­ev­er, due to re­stric­tions of Chro­mi­um-based browsers, it’s not pos­si­ble to down­load da­ta us­ing XMLHttpRequest when served from a lo­cal file-sys­tem. Be­cause of that, the search de­faults to pro­duc­ing a Base85-en­cod­ed rep­re­sen­ta­tion of the search bi­na­ry and load­ing that asyn­chronous­ly as a plain JavaScript file. This re­sults in the search da­ta be­ing 25% larg­er, but since this is for serv­ing from a lo­cal filesys­tem, it’s not con­sid­ered a prob­lem. If your docs are ac­cessed through a serv­er (or you don’t need Chrome sup­port), en­able the M_SEARCH_DOWNLOAD_BINARY op­tion.

If M_SEARCH_EXTERNAL_URL is spec­i­fied, full-text search us­ing an ex­ter­nal search en­gine is of­fered if noth­ing is found for giv­en string or if the us­er has JavaScript dis­abled. It’s rec­om­mend­ed to re­strict the search to a par­tic­u­lar do­main or add ad­di­tion­al key­words to the search query to fil­ter out ir­rel­e­vant re­sults. Ex­am­ple, us­ing Google search en­gine and re­strict­ing the search to a sub­do­main:

M_SEARCH_EXTERNAL_URL = "https://google.com/search?q=site:doc.magnum.graphics+{query}"

Con­tent

Brief and de­tailed de­scrip­tion is parsed as-is with the fol­low­ing mod­i­fi­ca­tions:

  • Func­tion pa­ram­e­ter doc­u­men­ta­tion, re­turn val­ue doc­u­men­ta­tion, tem­plate pa­ram­e­ter and ex­cep­tion doc­u­men­ta­tion is ex­tract­ed out of the text flow to al­low for more flex­i­ble styling. It’s al­so re­ordered to match pa­ram­e­ter or­der and warn­ings are emit­ted if there are mis­match­es.
  • To make text con­tent wrap bet­ter on nar­row screens, <wbr/> tags are added af­ter :: and _ in long sym­bols in link ti­tles and af­ter / in URLs.

Sin­gle-para­graph list items, func­tion pa­ram­e­ter de­scrip­tion, ta­ble cell con­tent and re­turn val­ue doc­u­men­ta­tion is stripped from the en­clos­ing <p> tag to make the out­put more com­pact. If mul­ti­ple para­graphs are present, noth­ing is stripped. In case of lists, they are then ren­dered in an in­flat­ed form. How­ev­er, in or­der to achieve even spac­ing al­so with sin­gle-para­graph items, it’s need­ed use some ex­plic­it markup. Adding <p></p> to a sin­gle-para­graph item will make sure the en­clos­ing <p> is not stripped.

/**
-   A list

    of multiple

    paragraphs.

-   Another item

    <p></p>

    -   A sub list

        Another paragraph
*/
  • A list

    of multiple

    paragraphs.

  • Another item

    • A sub list

      Another paragraph

Im­ages and fig­ures

To match the stock HTML out­put, im­ages that are marked with html tar­get are used. If im­age name is present, the im­age is ren­dered as a fig­ure with cap­tion. It’s pos­si­ble af­fect width/height of the im­age us­ing the sizespec pa­ram­e­ter (un­like stock Doxy­gen, which makes use of this field on­ly for La­TeX out­put and ig­nores it for HTML out­put). The pa­ram­e­ter is con­vert­ed to an in­line CSS width or height prop­er­ty, so the val­ue has to con­tain the units as well:

/**
@image image.png width=250px
*/

Dot graphs

Grapviz dot graphs from the @dot and @dotfile com­mands are ren­dered as an in­line SVG. Graph name and the sizespec works equiv­a­lent­ly to the Im­ages and fig­ures.

Pages, sec­tions and ta­ble of con­tents

Ta­ble of con­tents is un­con­di­tion­al­ly gen­er­at­ed for all com­pound doc­u­men­ta­tion pages and in­cludes both @section blocks in the de­tailed doc­u­men­ta­tion as well as the ref­er­ence sec­tions. If your doc­u­men­ta­tion is us­ing Mark­down-style head­ers (pre­fixed with ##, for ex­am­ple), the script is not able to gen­er­ate TOC en­tries for these. Up­on en­coun­ter­ing them, tt will warn and sug­gest to use the @section com­mand in­stead.

Ta­ble of con­tents for pages is gen­er­at­ed on­ly if they spec­i­fy @tableofcontents in their doc­u­men­ta­tion block.

Names­pace mem­bers in file scope

Doxy­gen by de­fault doesn’t ren­der names­pace mem­bers for file doc­u­men­ta­tion in its XML out­put. To match the be­hav­ior of stock HTML out­put, en­able the XML_NAMESPACE_MEMBERS_IN_FILE_SCOPE op­tion:

# Requires a patch to Doxygen 1.8.14, see below
XML_NAMESPACE_MEMBERS_IN_FILE_SCOPE = YES

Code high­light­ing

Ev­ery code snip­pet should be an­no­tat­ed with lan­guage-spe­cif­ic ex­ten­sion like in the ex­am­ple be­low. If not, the theme will as­sume C++ and emit a warn­ing on out­put. Lan­guage of snip­pets in­clud­ed via @include and re­lat­ed com­mands is au­tode­tect­ed from file­name.

/**
@code{.cpp}
int main() { }
@endcode
*/

Be­sides na­tive Pyg­ments map­ping of file ex­ten­sions to lan­guages, there are the fol­low­ing spe­cial cas­es:

File­name suf­fix De­tect­ed lan­guage
.h C++ (in­stead of C)
.h.cmake C++ (in­stead of CMake), as this ex­ten­sion is of­ten used for C++ head­ers that are pre­pro­cessed with CMake
.glsl GLSL. For some rea­son, stock Pyg­ments de­tect on­ly .vert, .frag and .geo ex­ten­sions as GLSL.
.conf INI (key-val­ue con­fig­u­ra­tion files)
.ansi Col­ored ter­mi­nal out­put. Use .shell-session pseu­do-ex­ten­sion for sim­ple un­col­ored ter­mi­nal out­put.
.xml-jinja Jin­ja tem­plates in XML markup (these don’t have any well-known ex­ten­sion oth­er­wise)
.html-jinja Jin­ja tem­plates in HTML markup (these don’t have any well-known ex­ten­sion oth­er­wise)
.jinja Jin­ja tem­plates (these don’t have any well-known ex­ten­sion oth­er­wise)

The theme has ex­per­i­men­tal sup­port for in­line code high­light­ing. In­line code is dis­tin­guished from code blocks us­ing the fol­low­ing rules:

  • Code that is de­lim­it­ed from sur­round­ing para­graphs with an emp­ty line is con­sid­ered as block.
  • Code that is com­ing from @include, @snippet and re­lat­ed com­mands that paste ex­ter­nal file con­tent is al­ways con­sid­ered as block.
  • Code that is com­ing from @code and is not alone in a para­graph is con­sid­ered as in­line.
  • For com­pat­i­bil­i­ty rea­sons, if code that is de­tect­ed as in­line con­sists of more than one line, it’s ren­dered as code block and a warn­ing is print­ed to out­put.

In­line high­light­ed code is writ­ten al­so us­ing the @code com­mand, but as writ­ing things like

/** Returns @code{.cpp} Magnum::Vector2 @endcode, which is
    @code{.glsl} vec2 @endcode in GLSL. */

is too ver­bose, it’s ad­vised to con­fig­ure some alias­es in your Doxyfile-mcss. For ex­am­ple, you can con­fig­ure an alias for gen­er­al in­line code snip­pets and short­er ver­sions for com­mon­ly used lan­guages like C++ and CMake.

ALIASES += \
    "cb{1}=@code{\1}" \
    "ce=@endcode" \
    "cpp=@code{.cpp}" \
    "cmake=@code{.cmake}"

With this in place the above could be then writ­ten sim­ply as:

/** Returns @cpp Magnum::Vector2 @ce, which is @cb{.glsl} vec2 @ce in GLSL. */

If you need to pre­serve com­pat­i­bil­i­ty with stock Doxy­gen HTML out­put (be­cause it ren­ders all @code sec­tions as blocks), use the fol­low­ing fall­back alias­es in the orig­i­nal Doxyfile:

ALIASES += \
    "cb{1}=<tt>" \
    "ce=</tt>" \
    "cpp=<tt>" \
    "cmake=<tt>"

Theme-spe­cif­ic com­mands

It’s pos­si­ble to in­sert cus­tom m.css class­es in­to the Doxy­gen out­put. Add the fol­low­ing to your Doxyfile-mcss:

ALIASES += \
    "m_div{1}=@xmlonly<mcss:div xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
    "m_enddiv=@xmlonly</mcss:div>@endxmlonly" \
    "m_span{1}=@xmlonly<mcss:span xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
    "m_endspan=@xmlonly</mcss:span>@endxmlonly" \
    "m_class{1}=@xmlonly<mcss:class xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\" />@endxmlonly" \
    "m_footernavigation=@xmlonly<mcss:footernavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" />@endxmlonly" \
    "m_examplenavigation{2}=@xmlonly<mcss:examplenavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:page=\"\1\" mcss:prefix=\"\2\" />@endxmlonly" \
    "m_keywords{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"\1\" />@endxmlonly" \
    "m_keyword{3}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keyword=\"\1\" mcss:title=\"\2\" mcss:suffix-length=\"\3\" />@endxmlonly" \
    "m_enum_values_as_keywords=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:enum-values-as-keywords=\"true\" />@endxmlonly"

If you need back­wards com­pat­i­bil­i­ty with stock Doxy­gen HTML out­put, just make the alias­es emp­ty in your orig­i­nal Doxyfile. Note that you can re­name the alias­es how­ev­er you want to fit your nam­ing scheme.

ALIASES += \
    "m_div{1}=" \
    "m_enddiv=" \
    "m_span{1}=" \
    "m_endspan=" \
    "m_class{1}=" \
    "m_footernavigation=" \
    "m_examplenavigation{2}" \
    "m_keywords{1}=" \
    "m_keyword{3}=" \
    "m_enum_values_as_keywords="

With @m_class it’s pos­si­ble to add CSS class­es to the im­me­di­ate­ly fol­low­ing para­graph, im­age, ta­ble, list or math for­mu­la block. When used in­line, it af­fects the im­me­di­ate­ly fol­low­ing em­pha­sis, strong text, link or in­line math for­mu­la. Ex­am­ple us­age:

/**
A green formula:

@m_class{m-success}

@f[
    e^{i \pi} + 1 = 0
@f]

Use the @m_class{m-label m-warning} **Shift** key.
*/

A green for­mu­la:

e^{i \pi} + 1 = 0

Use the Shift key.

The builtin @parblock com­mand can be com­bined with @m_class to wrap a block of HTML code in a <div> and add CSS class­es to it. With @m_div and @m_span it’s pos­si­ble to wrap in­di­vid­u­al para­graphs or in­line text in <div> / <span> and add CSS class­es to them with­out any ex­tra el­e­ments be­ing added. Ex­am­ple us­age and cor­re­spond­ing ren­dered HTML out­put:

/**
@m_class{m-note m-dim m-text-center}
This block is rendered in a dim note.

Centered.
@parblock

@m_div{m-button m-primary} <a href="http://doc.magnum.graphics/">@m_div{m-big}See
it live! @m_enddiv @m_div{m-small} uses the m.css theme @m_enddiv </a> @m_enddiv

This text contains a @span{m-text m-success} green @endspan word.
*/

This text con­tains a green word.

It’s pos­si­ble to com­bine @par with @parblock to cre­ate blocks, notes and oth­er m.css com­po­nents with ar­bi­trary con­tents. The @par com­mand vi­su­als can be ful­ly over­ri­den by putting @m_class in front, the @parblock af­ter will en­sure ev­ery­thing will be­long in­side. A bit re­cur­sive ex­am­ple:

/**
@m_class{m-block m-success} @par How to get the answer
@parblock
    It's simple:

    @m_class{m-code-figure} @parblock
        @code{.cpp}
        // this is the code
        printf("The answer to the universe and everything is %d.", 5*9);
        @endcode

        @code{.shell-session}
        The answer to the universe and everything is 42.
        @endcode
    @endparblock
@endparblock
*/

The @m_footernavigation com­mand is sim­i­lar to @tableofcontents, but across pages — if a page is a sub­page of some oth­er page and this com­mand is present in page de­tailed de­scrip­tion, it will cause the foot­er of the ren­dered page to con­tain a link to pre­vi­ous, par­ent and next page ac­cord­ing to de­fined page or­der.

The @m_examplenavigation com­mand is able to put bread­crumb nav­i­ga­tion to par­ent page(s) of @example list­ings in or­der to make it eas­i­er for users to re­turn back from ex­am­ple source code to a tu­to­ri­al page, for ex­am­ple. When used in com­bi­na­tion with @m_footernavigation, nav­i­ga­tion to par­ent page and to prev/next file of the same ex­am­ple is put at the bot­tom of the page. The @m_examplenavigation com­mand takes two ar­gu­ments, first is the par­ent page for this ex­am­ple (used to build the bread­crumb and foot­er nav­i­ga­tion), sec­ond is ex­am­ple path pre­fix (which is then stripped from page ti­tle and is al­so used to dis­cov­er which ex­am­ple files be­long to­geth­er). Ex­am­ple us­age — the @m_examplenavigation and @m_footernavigation com­mands are sim­ply ap­pend­ed the an ex­ist­ing @example com­mand.

/**
@example helloworld/CMakeLists.txt @m_examplenavigation{example,helloworld/} @m_footernavigation
@example helloworld/configure.h.cmake @m_examplenavigation{example,helloworld/} @m_footernavigation
@example helloworld/main.cpp @m_examplenavigation{example,helloworld/} @m_footernavigation
*/

The pur­pose of @m_keywords, @m_keyword and @m_enum_values_as_keywords com­mand is to add fur­ther search key­words to giv­en doc­u­ment­ed sym­bols. Use @m_keywords to en­ter white­space-sep­a­rat­ed list of key­words. The @m_enum_values_as_keywords com­mand will add ini­tial­iz­ers of giv­en enum val­ues as key­words for each cor­re­spond­ing val­ue, it’s ig­nored when not used in enum de­scrip­tion block. In the fol­low­ing ex­am­ple, an OpenGL wrap­per API adds GL API names as key­words for eas­i­er dis­cov­er­abil­i­ty, so e.g. the Texture2D::setStorage() func­tion is al­so found when typ­ing glTexStorage2D() in­to the search field, or the Renderer::Feature::DepthTest enum val­ue is found when en­ter­ing GL_DEPTH_TEST:

/**
 * @brief Set texture storage
 *
 * @m_keywords{glTexStorage2D() glTextureStorage2D()}
 */
Texture2D& Texture2D::setStorage(...);

/**
 * @brief Renderer feature
 *
 * @m_enum_values_as_keywords
 */
enum class RendererFeature: GLenum {
    /** Depth test */
    DepthTest = GL_DEPTH_TEST,

    ...
};

The @m_keyword com­mand is use­ful if you need to en­ter a key­word con­tain­ing spa­ces, the op­tion­al sec­ond and third pa­ram­e­ter al­low you to spec­i­fy a dif­fer­ent ti­tle and suf­fix length. Ex­am­ple us­age — in the first case be­low, the page will be dis­cov­er­able both us­ing its pri­ma­ry ti­tle and us­ing TCB spline sup­port, in the sec­ond and third case the two over­loads of the lerp() func­tion are dis­cov­er­able al­so via mix(), dis­play­ing ei­ther GLSL mix() or GLSL mix(gen­Type, gen­Type, float) in the search re­sults. The last pa­ram­e­ter is suf­fix length, need­ed to cor­rect­ly higlight the mix sub­string when there are ad­di­tion­al char­ac­ters at the end of the ti­tle. If not spec­i­fied, it de­faults to 0, mean­ing the search string is a suf­fix of the ti­tle.

/**
 * @page splines-tcb Kochanek–Bartels spline support
 * @m_keyword{TCB spline support,,}
 */

/**
 * @brief Clamp a value
 * @m_keyword{clamp(),GLSL clamp(),}
 */
float lerp(float x, float y, float a);

/**
 * @brief Clamp a value
 * @m_keyword{mix(),GLSL mix(genType\, genType\, float),23}
 */
template<class T> lerp(const T& x, const T& y, float a);

Com­mand-line op­tions

./dox2html5.py [-h] [--templates TEMPLATES] [--wildcard WILDCARD]
               [--index-pages INDEX_PAGES [INDEX_PAGES ...]]
               [--no-doxygen] [--search-no-subtree-merging]
               [--search-no-lookahead-barriers]
               [--search-no-prefix-merging] [--sort-globbed-files]
               [--debug]
               doxyfile

Ar­gu­ments:

  • doxyfile — where the Doxy­file is

Op­tions:

  • -h, --help — show this help mes­sage and ex­it
  • --templates TEMPLATES — tem­plate di­rec­to­ry. De­faults to the templates/ sub­di­rec­to­ry if not set.
  • --wildcard WILDCARD — on­ly process files match­ing the wild­card. Use­ful for de­bug­ging to speed up / re­strict the pro­cess­ing to a sub­set of files. De­faults to *.xml if not set.
  • --index-pages INDEX_PAGES [INDEX_PAGES ...] — in­dex page tem­plates. By de­fault, if not set, the in­dex pages are match­ing stock Doxy­gen, i.e. annotated.html, files.html, modules.html, namespaces.html and pages.html. See Nav­i­ga­tion page tem­plates sec­tion be­low for more in­for­ma­tion.
  • --no-doxygen — don’t run Doxy­gen be­fore. By de­fault Doxy­gen is run be­fore the script to re­fresh the gen­er­at­ed XML out­put.
  • --search-no-subtree-merging — don’t op­ti­mize search da­ta size by merg­ing sub­trees
  • --search-no-lookahead-barriers — don’t in­sert search looka­head bar­ri­ers that im­prove search re­sult rel­e­vance
  • --search-no-prefix-merging — don’t merge search re­sult pre­fix­es
  • --sort-globbed-files — sort globbed files for bet­ter re­pro­ducibil­i­ty
  • --debug — ver­bose de­bug out­put. Use­ful for de­bug­ging.

Trou­bleshoot­ing

Gen­er­at­ed out­put is (most­ly) emp­ty

As stat­ed in the Fea­tures sec­tion above; files, di­rec­to­ries and sym­bols with no doc­u­men­ta­tion are not present in the out­put at all. In par­tic­u­lar, when all your sources are un­der a sub­di­rec­to­ry and/or a names­pace and that sub­di­rec­to­ry / names­pace is not doc­u­ment­ed, the file / sym­bol tree will not show any­thing.

A sim­ple @brief en­try is enough to fix this. For ex­am­ple, if you have a MorningCoffee::CleanCup class that’s avail­able from #include <MorningCoffee/CleanCup.h>, these doc­u­men­ta­tion blocks are enough to have the di­rec­to­ry, file, names­pace and al­so the class ap­pear in the file / sym­bol tree:

/** @dir MorningCoffee
 * @brief Namespace @ref MorningCoffee
 */
/** @namespace MorningCoffee
 * @brief The Morning Coffee library
 */
// CleanCup.h

/** @file
 * @brief Class @ref CleanCup
 */

namespace MorningCoffee {

    /**
     * @brief A clean cup
     */
    class CleanCup {

    ...

To help you de­bug­ging this, run dox2html5.py with the --debug op­tion. and look for en­tries that look like be­low. Be­cause there are many false pos­i­tives, this in­for­ma­tion is not present in the non-ver­bose out­put.

DEBUG:root:dir_22305cb0964bbe63c21991dd2265ce48.xml: neither brief nor
detailed description present, skipping

Out­put is not styled

If your Doxyfile con­tains a non-emp­ty HTML_EXTRA_STYLESHEET op­tion, m.css will use CSS files from there in­stead of the builtin ones. Ei­ther over­ride it to an emp­ty val­ue in your Doxyfile-mcss or spec­i­fy prop­er CSS files ex­plic­it­ly as men­tioned in the Theme se­lec­tion sec­tion.

Gen­er­at­ing takes too long, crash­es, as­serts or gen­er­al­ly fails

The XML out­put gen­er­at­ed by Doxy­gen is un­der­spec­i­fied and un­nec­es­sar­i­ly com­plex, so it might very well hap­pen that your doc­u­men­ta­tion trig­gers some untest­ed code path. The script is de­signed to fail ear­ly and hard in­stead of silent­ly con­tin­u­ing and pro­duc­ing wrong out­put — if you see an as­ser­tion fail­ure or a crash or things seem to be stuck, you can do the fol­low­ing:

  • Re-run the script with the --debug op­tion. That will list what XML file is be­ing pro­cessed at the mo­ment and helps you nar­row down the is­sue to a par­tic­u­lar file.
  • At the mo­ment, math for­mu­la ren­der­ing is not batched and takes very long, as La­TeX is start­ed sep­a­rate­ly for ev­ery oc­cur­rence. Help in this area is wel­come.
  • Try with a fresh­ly gen­er­at­ed Doxyfile. If it stops hap­pen­ing, the prob­lem might be re­lat­ed to some con­fig­u­ra­tion op­tion (but maybe al­so an alias or pre­proces­sor #define that’s not de­fined any­more)
  • m.css cur­rent­ly ex­pects on­ly C++ in­put. If you have Python or some oth­er lan­guage on in­put, it will get very con­fused very fast. This can be al­so caused by a file be­ing in­clud­ed by ac­ci­dent, re­strict the INPUT and FILE_PATTERNS op­tions to pre­vent that.
  • Try to nar­row the prob­lem down to a small code snip­pet and sub­mit a bug re­port with giv­en snip­pet and all rel­e­vant in­fo (es­pe­cial­ly Doxy­gen ver­sion). Or ask in the Git­ter chat. If I’m not able to pro­vide a fix right away, there’s a great chance I’ve al­ready seen such prob­lem and can sug­gest a work­around at least.

Cus­tomiz­ing the tem­plate

The rest of the doc­u­men­ta­tion ex­plains how to cus­tom­ize the builtin tem­plate to bet­ter suit your needs. Each doc­u­men­ta­tion file is gen­er­at­ed from one of the tem­plate files that are bun­dled with the script. How­ev­er, it’s pos­si­ble to pro­vide your own Jin­ja2 tem­plate files for cus­tom­ized ex­pe­ri­ence as well as mod­i­fy the CSS styling.

CSS files

By de­fault, com­piled CSS files are used to re­duce amount of HTTP re­quests and band­width need­ed for view­ing the doc­u­men­ta­tion. How­ev­er, for eas­i­er cus­tomiza­tion and de­bug­ging it’s bet­ter to use the un­pro­cessed stylesheets. The HTML_EXTRA_STYLESHEET lists all files that go to the <link rel="stylesheet" /> in the re­sult­ing HTML markup, while HTML_EXTRA_FILES lists the in­di­rect­ly ref­er­enced files that need to be copied to the out­put as well. Be­low is an ex­am­ple con­fig­u­ra­tion cor­re­spond­ing to the dark theme:

HTML_EXTRA_STYLESHEET = \
    https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600 \
    ../css/m-dark.css \
    ../css/m-doxygen.css
HTML_EXTRA_FILES = \
    ../css/m-grid.css \
    ../css/m-components.css \
    ../css/pygments-dark.css \
    ../css/pygments-console.css
M_THEME_COLOR = #22272e

Af­ter mak­ing de­sired changes to the source files, it’s pos­si­ble to post­pro­cess them back to the com­piled ver­sion us­ing the postprocess.py util­i­ty as ex­plained in the CSS themes doc­u­men­ta­tion. In case of the dark theme, the m-dark+doxygen.compiled.css and m-dark.doxygen.compiled.css files are pro­duced like this:

cd css
./postprocess.py m-dark.css m-doxygen.css -o m-dark+doxygen.compiled.css
./postprocess.py m-dark.css m-doxygen.css --no-import -o m-dark.doxygen.compiled.css

Com­pound doc­u­men­ta­tion tem­plate

For com­pound doc­u­men­ta­tion one out­put HTML file cor­re­sponds to one in­put XML file and there are some nam­ing con­ven­tions im­posed by Doxy­gen.

File­name Use
class.html Class doc­u­men­ta­tion, read from class*.xml and saved as class*.html
dir.html Di­rec­to­ry doc­u­men­ta­tion, read from dir_*.xml and saved as dir_*.html
example.html Ex­am­ple code list­ing, read from *-example.xml and saved as *-example.html
file.html File doc­u­men­ta­tion, read from *.xml and saved as *.html
namespace.html Names­pace doc­u­men­ta­tion, read fron namespace*.xml and saved as namespace*.html
group.html Mod­ule doc­u­men­ta­tion, read fron group_*.xml and saved as group_*.html
page.html Page, read from *.xml/indexpage.xml and saved as *.html/index.html
struct.html Struct doc­u­men­ta­tion, read from struct*.xml and saved as struct*.html
union.html Union doc­u­men­ta­tion, read from union*.xml and saved as union*.html

Each tem­plate is passed a sub­set of the Doxyfile con­fig­u­ra­tion val­ues from the Con­fig­u­ra­tion ta­ble. Most val­ues are pro­vid­ed as-is de­pend­ing on their type, so ei­ther strings, bool­eans, or lists of strings. The ex­cep­tions are:

  • The M_LINKS_NAVBAR1 and M_LINKS_NAVBAR2 are pro­cessed to tu­ples in a form (html, title, url, id, sub) where ei­ther html is a full HTML code for the link and title, url id is emp­ty; or html is None, title and url is a link ti­tle and URL and id is com­pound ID (to use for high­light­ing ac­tive menu item). The last item, sub is a list op­tion­al­ly con­tain­ing sub-menu items. The sub-menu items are in a sim­i­lar­ly formed tu­ple, (html, title, url, id).
  • The M_FAVICON is con­vert­ed to a tu­ple of (url, type) where url is the fav­i­con URL and type is fav­i­con MIME type to pop­u­late the type at­tribute of <link rel="favicon" />.
and in ad­di­tion the fol­low­ing vari­ables:
Vari­able De­scrip­tion
FILENAME Name of giv­en out­put file
DOXYGEN_VERSION Ver­sion of Doxy­gen that gen­er­at­ed giv­en XML file

In ad­di­tion to builtin Jin­ja2 fil­ters, the basename_or_url fil­ter re­turns ei­ther a base­name of file path, if the path is rel­a­tive; or a full URL, if the ar­gu­ment is an ab­so­lute URL. It’s use­ful in cas­es like this:

{% for css in HTML_EXTRA_STYLESHEET %}
<link rel="stylesheet" href="{{ css|basename_or_url }}" />
{% endfor %}

The ac­tu­al page con­tents are pro­vid­ed in a compound ob­ject, which has the fol­low­ing prop­er­ties. All ex­posed da­ta are meant to be past­ed di­rect­ly to the HTML code with­out any es­cap­ing.

Prop­er­ty De­scrip­tion
compound.kind One of 'class', 'dir', 'example', 'file', 'group', 'namespace', 'page', 'struct', 'union', used to choose a tem­plate file from above
compound.id Unique com­pound iden­ti­fi­er, usu­al­ly cor­re­spond­ing to out­put file name
compound.url Com­pound URL (or where this file will be saved)
compound.name Com­pound name
compound.templates Tem­plate spec­i­fi­ca­tion. Set on­ly for class­es. See Tem­plate prop­er­ties for de­tails.
compound.has_template_details If there is a de­tailed doc­u­men­ta­tion of tem­plate pa­ram­e­ters
compound.sections Sec­tions of de­tailed de­scrip­tion. See Nav­i­ga­tion prop­er­ties for de­tails.
compound.footer_navigation Foot­er nav­i­ga­tion of a page. See Nav­i­ga­tion prop­er­ties for de­tails.
compound.brief Brief de­scrip­tion. Can be emp­ty. 1
compound.is_deprecated Whether the com­pound is dep­re­cat­ed. 7
compound.description De­tailed de­scrip­tion. Can be emp­ty. 2
compound.modules List of sub­mod­ules in this com­pound. Set on­ly for mod­ules. See Mod­ule prop­er­ties for de­tails.
compound.dirs List of di­rec­to­ries in this com­pound. Set on­ly for di­rec­to­ries. See Di­rec­to­ry prop­er­ties for de­tails.
compound.files List of files in this com­pound. Set on­ly for di­rec­to­ries and files. See File prop­er­ties for de­tails.
compound.namespaces List of names­paces in this com­pound. Set on­ly for files and names­paces. See Names­pace prop­er­ties for de­tails.
compound.classes List of class­es in this com­pound. Set on­ly for files and names­paces. See Class prop­er­ties for de­tails.
compound.base_classes List of base class­es in this com­pound. Set on­ly for class­es. See Class prop­er­ties for de­tails.
compound.derived_classes List of de­rived class­es in this com­pound. Set on­ly for class­es. See Class prop­er­ties for de­tails.
compound.enums List of enums in this com­pound. Set on­ly for files and names­paces. See Enum prop­er­ties for de­tails.
compound.typedefs List of type­defs in this com­pound. Set on­ly for files and names­paces. See Type­def prop­er­ties for de­tails.
compound.funcs List of func­tions in this com­pound. Set on­ly for files and names­paces. See Func­tion prop­er­ties for de­tails.
compound.vars List of vari­ables in this com­pound. Set on­ly for files and names­paces. See Vari­able prop­er­ties for de­tails.
compound.defines List of de­fines in this com­pound. Set on­ly for files. See De­fine prop­er­ties for de­tails.
compound.public_types List of pub­lic types. Set on­ly for class­es. See Type prop­er­ties for de­tails.
compound.public_static_funcs List of pub­lic stat­ic func­tions. Set on­ly for class­es. See Func­tion prop­er­ties for de­tails.
compound.public_funcs List of pub­lic func­tions. Set on­ly for class­es. See Func­tion prop­er­ties for de­tails.
compound.signals List of Qt sig­nals. Set on­ly for class­es. See Func­tion prop­er­ties for de­tails.
compound.public_slots List of pub­lic Qt slots. Set on­ly for class­es. See Func­tion prop­er­ties for de­tails.
compound.public_static_vars List of pub­lic stat­ic vari­ables. Set on­ly for class­es. See Vari­able prop­er­ties for de­tails.
compound.public_vars List of pub­lic vari­ables. Set on­ly for class­es. See Vari­able prop­er­ties for de­tails.
compound.protected_types List of pro­tect­ed types. Set on­ly for class­es. See Type prop­er­ties for de­tails.
compound.protected_static_funcs List of pro­tect­ed stat­ic func­tions. Set on­ly for class­es. See Func­tion prop­er­ties for de­tails.
compound.protected_funcs List of pro­tect­ed func­tions. Set on­ly for class­es. See Func­tion prop­er­ties for de­tails.
compound.protected_slots List of pro­tect­ed Qt slots. Set on­ly for class­es. See Func­tion prop­er­ties for de­tails.
compound.protected_static_vars List of pro­tect­ed stat­ic vari­ables. Set on­ly for class­es. See Vari­able prop­er­ties for de­tails.
compound.protected_vars List of pro­tect­ed vari­ables. Set on­ly for class­es. See Vari­able prop­er­ties for de­tails.
compound.private_funcs List of doc­u­ment­ed pri­vate vir­tu­al func­tions. Set on­ly for class­es. See Func­tion prop­er­ties for de­tails.
compound.private_slots List of doc­u­ment­ed pri­vate vir­tu­al Qt slots. Set on­ly for class­es. See Func­tion prop­er­ties for de­tails.
compound.friend_funcs List of doc­u­ment­ed friend func­tions. Set on­ly for class­es. See Func­tion prop­er­ties for de­tails.
compound.related List of re­lat­ed non-mem­ber sym­bols. Set on­ly for class­es. See Re­lat­ed prop­er­ties for de­tails.
compound.groups List of us­er-de­fined groups in this com­pound. See Group prop­er­ties for de­tails.
compound.has_enum_details If there is at least one enum with full de­scrip­tion block 5
compound.has_typedef_details If there is at least one type­def with full de­scrip­tion block 5
compound.has_func_details If there is at least one func­tion with full de­scrip­tion block 5
compound.has_var_details If there is at least one vari­able with full de­scrip­tion block 5
compound.has_define_details If there is at least one de­fine with full de­scrip­tion block 5
compound.breadcrumb List of (title, URL) tu­ples for bread­crumb nav­i­ga­tion. Set on­ly for class­es, di­rec­to­ries, files, names­paces and pages.
compound.prefix_wbr Ful­ly-qual­i­fied sym­bol pre­fix for giv­en com­pound with trail­ing :: with <wbr/> tag be­fore ev­ery ::. Set on­ly for class­es, names­paces, structs and unions; on tem­plat­ed class­es con­tains al­so the list of tem­plate pa­ram­e­ter names.

Mod­ule prop­er­ties

The compound.modules prop­er­ty con­tains a list of mod­ules, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
module.url URL of the file con­tain­ing de­tailed mod­ule docs
module.name Mod­ule name (just the leaf)
module.brief Brief de­scrip­tion. Can be emp­ty. 1
module.is_deprecated Whether the mod­ule is dep­re­cat­ed. 7

Di­rec­to­ry prop­er­ties

The compound.dirs prop­er­ty con­tains a list of di­rec­to­ries, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
dir.url URL of the file con­tain­ing de­tailed di­rec­to­ry docs
dir.name Di­rec­to­ry name (just the leaf)
dir.brief Brief de­scrip­tion. Can be emp­ty. 1
dir.is_deprecated Whether the di­rec­to­ry is dep­re­cat­ed. 7

File prop­er­ties

The compound.files prop­er­ty con­tains a list of files, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
file.url URL of the file con­tain­ing de­tailed file docs
file.name File name (just the leaf)
file.brief Brief de­scrip­tion. Can be emp­ty. 1
file.is_deprecated Whether the file is dep­re­cat­ed. 7

Names­pace prop­er­ties

The compound.namespaces prop­er­ty con­tains a list of names­paces, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
namespace.url URL of the file con­tain­ing de­tailed names­pace docs
namespace.name Names­pace name. Ful­ly qual­i­fied in case it’s in a file doc­u­men­ta­tion, just the leaf name if in a names­pace doc­u­men­ta­tion.
namespace.brief Brief de­scrip­tion. Can be emp­ty. 1
namespace.is_deprecated Whether the names­pace is dep­re­cat­ed. 7

Class prop­er­ties

The compound.classes prop­er­ty con­tains a list of class­es, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
class.kind One of 'class', 'struct', 'union'
class.url URL of the file con­tain­ing de­tailed class docs
class.name Class name. Ful­ly qual­i­fied in case it’s in a file doc­u­men­ta­tion, just the leaf name if in a names­pace doc­u­men­ta­tion.
class.templates Tem­plate spec­i­fi­ca­tion. See Tem­plate prop­er­ties for de­tails.
class.brief Brief de­scrip­tion. Can be emp­ty. 1
class.is_deprecated Whether the class is dep­re­cat­ed. 7
class.is_protected Whether this is a pro­tect­ed base class. Set on­ly for base class­es.
class.is_virtual Whether this is a vir­tu­al base class. Set on­ly for base class­es.

Enum prop­er­ties

The compound.enums prop­er­ty con­tains a list of enums, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
enum.base_url Base URL of file con­tain­ing de­tailed de­scrip­tion 3
enum.id Iden­ti­fi­er hash 3
enum.type Enum type or emp­ty if im­plic­it­ly typed 6
enum.is_strong If the enum is strong
enum.name Enum name 4
enum.brief Brief de­scrip­tion. Can be emp­ty. 1
enum.description De­tailed de­scrip­tion. Can be emp­ty. 2
enum.has_details If there is enough con­tent for the full de­scrip­tion block 5
enum.is_deprecated Whether the enum is dep­re­cat­ed. 7
enum.is_protected If the enum is protected. Set on­ly for mem­ber types.
enum.values List of enum val­ues
enum.has_value_details If the enum val­ues have de­scrip­tion

Ev­ery item of enum.values has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
value.base_url Base URL of file con­tain­ing de­tailed de­scrip­tion 3
value.id Iden­ti­fi­er hash 3
value.name Val­ue name 4
value.initializer Val­ue ini­tial­iz­er. Can be emp­ty. 1
value.is_deprecated Whether the val­ue is dep­re­cat­ed. 7
value.brief Brief de­scrip­tion. Can be emp­ty. 1
value.description De­tailed de­scrip­tion. Can be emp­ty. 2

Type­def prop­er­ties

The compound.typedefs prop­er­ty con­tains a list of type­defs, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
typedef.base_url Base URL of file con­tain­ing de­tailed de­scrip­tion 3
typedef.id Iden­ti­fi­er hash 3
typedef.is_using Whether it is a typedef or an using
typedef.type Type­def type, or what all goes be­fore the name for func­tion point­er type­defs 6
typedef.args Type­def ar­gu­ments, or what all goes af­ter the name for func­tion point­er type­defs 6
typedef.name Type­def name 4
typedef.templates Tem­plate spec­i­fi­ca­tion. Set on­ly in case of using. . See Tem­plate prop­er­ties for de­tails.
typedef.brief Brief de­scrip­tion. Can be emp­ty. 1
typedef.is_deprecated Whether the type­def is dep­re­cat­ed. 7
typedef.description De­tailed de­scrip­tion. Can be emp­ty. 2
typedef.has_details If there is enough con­tent for the full de­scrip­tion block 4
typedef.is_protected If the type­def is protected. Set on­ly for mem­ber types.

Func­tion prop­er­ties

The commpound.funcs, compound.public_static_funcs, compound.public_funcs, compound.signals, compound.public_slots, compound.protected_static_funcs, compound.protected_funcs, compound.protected_slots, compound.private_funcs, compound.private_slots, compound.friend_funcs and compound.related_funcs prop­er­ties con­tain a list of func­tions, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
func.base_url Base URL of file con­tain­ing de­tailed de­scrip­tion 3
func.id Iden­ti­fi­er hash 3
func.type Func­tion re­turn type 6
func.name Func­tion name 4
func.templates Tem­plate spec­i­fi­ca­tion. See Tem­plate prop­er­ties for de­tails.
func.has_template_details If tem­plate pa­ram­e­ters have de­scrip­tion
func.params List of func­tion pa­ram­e­ters. See be­low for de­tails.
func.has_param_details If func­tion pa­ram­e­ters have de­scrip­tion
func.return_value Re­turn val­ue de­scrip­tion. Can be emp­ty.
func.return_values De­scrip­tion of par­tic­u­lar re­turn val­ues. See be­low for de­tails.
func.exceptions De­scrip­tion of par­tic­u­lar ex­cep­tion types. See be­low for de­tails.
func.brief Brief de­scrip­tion. Can be emp­ty. 1
func.description De­tailed de­scrip­tion. Can be emp­ty. 2
func.has_details If there is enough con­tent for the full de­scrip­tion block 5
func.prefix Func­tion sig­na­ture pre­fix, con­tain­ing key­words such as static. In­for­ma­tion about constexprness, explicitness and virtuality is re­moved from the pre­fix and avail­able via oth­er prop­er­ties.
func.suffix Func­tion sig­na­ture suf­fix, con­tain­ing key­words such as const and r-val­ue over­loads. In­for­ma­tion about noexcept, pure virtuality and deleted / defaulted func­tions is re­moved from the suf­fix and avail­able via oth­er prop­er­ties.
func.is_deprecated Whether the func­tion is dep­re­cat­ed. 7
func.is_protected If the func­tion is protected. Set on­ly for mem­ber func­tions.
func.is_private If the func­tion is private. Set on­ly for mem­ber func­tions.
func.is_explicit If the func­tion is explicit. Set on­ly for mem­ber func­tions.
func.is_virtual If the func­tion is virtual. Set on­ly for mem­ber func­tions.
func.is_pure_virtual If the func­tion is pure virtual. Set on­ly for mem­ber func­tions.
func.is_noexcept If the func­tion is noexcept
func.is_constexpr If the func­tion is constexpr
func.is_defaulted If the func­tion is defaulted
func.is_deleted If the func­tion is deleted
func.is_signal If the func­tion is a Qt sig­nal. Set on­ly for mem­ber func­tions.
func.is_slot If the func­tion is a Qt slot. Set on­ly for mem­ber func­tions.

The func.params is a list of func­tion pa­ram­e­ters and their de­scrip­tion. Each item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
param.name Pa­ram­e­ter name (if not anony­mous)
param.type Pa­ram­e­ter type, to­geth­er with ar­ray spec­i­fi­ca­tion 6
param.type_name Pa­ram­e­ter type, to­geth­er with name and ar­ray spec­i­fi­ca­tion 6
param.default De­fault pa­ram­e­ter val­ue, if any 6
param.description Op­tion­al pa­ram­e­ter de­scrip­tion. If set, func.has_param_details is set as well.
param.direction Pa­ram­e­ter di­rec­tion. One of 'in', 'out', 'inout' or '' if un­spec­i­fied.

The func.return_values prop­er­ty is a list of re­turn val­ues and their de­scrip­tion (in con­tract to func.return_value, which is just a sin­gle de­scrip­tion). Each item is a tu­ple of (value, description). Can be emp­ty, it can al­so hap­pen that both func.return_value and func.return_values are re­sent. Sim­i­lar­ly, the func.exceptions prop­er­ty is a list of (type, description) tu­ples.

Vari­able prop­er­ties

The compound.vars, compound.public_vars and compound.protected_vars prop­er­ties con­tain a list of vari­ables, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
var.base_url Base URL of file con­tain­ing de­tailed de­scrip­tion 3
var.id Iden­ti­fi­er hash 3
var.type Vari­able type 6
var.name Vari­able name 4
var.brief Brief de­scrip­tion. Can be emp­ty. 1
var.description De­tailed de­scrip­tion. Can be emp­ty. 2
var.has_details If there is enough con­tent for the full de­scrip­tion block 5
var.is_deprecated Whether the vari­able is dep­re­cat­ed. 7
var.is_static If the vari­able is static. Set on­ly for mem­ber vari­ables.
var.is_protected If the vari­able is protected. Set on­ly for mem­ber vari­ables.
var.is_constexpr If the vari­able is constexpr

De­fine prop­er­ties

The compound.defines prop­er­ty con­tains a list of de­fines, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
define.id Iden­ti­fi­er hash 3
define.name De­fine name
define.params List of macro pa­ram­e­ter names. See be­low for de­tails.
define.has_param_details If de­fine pa­ram­e­ters have de­scrip­tion
define.return_value Re­turn val­ue de­scrip­tion. Can be emp­ty.
define.brief Brief de­scrip­tion. Can be emp­ty. 1
define.description De­tailed de­scrip­tion. Can be emp­ty. 2
define.is_deprecated Whether the de­fine is dep­re­cat­ed. 7
define.has_details If there is enough con­tent for the full de­scrip­tion block 5

The define.params is set to None if the macro is just a vari­able. If it’s a func­tion, each item is a tu­ple con­sist­ing of name and op­tion­al de­scrip­tion. If the de­scrip­tion is set, define.has_param_details is set as well. You can use {% if define.params != None %} to dis­am­biguate be­tween pre­proces­sor macros and vari­ables in your code.

Type prop­er­ties

For class­es, the compound.public_types and compound.protected_types con­tains a list of (kind, type) tu­ples, where kind is one of 'class', 'enum' or 'typedef' and type is a cor­re­spond­ing type of ob­ject de­scribed above.

Tem­plate prop­er­ties

The compound.templates, typedef.templates and func.templates prop­er­ties con­tain ei­ther None if giv­en sym­bol is a full tem­plate spe­cial­iza­tion or a list of tem­plate pa­ram­e­ters, where ev­ery item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
template.type Tem­plate pa­ram­e­ter type (class, typename or a type)
template.name Tem­plate pa­ram­e­ter name
template.default Tem­plate de­fault val­ue. Can be emp­ty.
template.description Op­tion­al tem­plate de­scrip­tion. If set, i.has_template_details is set as well.

You can use {% if i.templates != None %} to test for the field pres­ence in your code.

Group prop­er­ties

The compound.groups con­tains a list of us­er-de­fined groups. Each item has the fol­low­ing prop­er­ties:

Prop­er­ty De­scrip­tion
group.id Group iden­ti­fi­er 3
group.name Group name
group.description Group de­scrip­tion 2
group.members Group mem­bers. Each item is a tu­ple of (kind, member), where kind is one of 'namespace', 'class', 'enum', 'typedef', 'func', 'var' or 'define' and member is a cor­re­spond­ing type of ob­ject de­scribed above.