Doc generators » Doxygen C++ theme

A mod­ern, mo­bile-friendly drop-in re­place­ment for the stock Doxy­gen HTML out­put, with a first-class search func­tion­al­ity. Gen­er­ated from Doxy­gen-pro­duced XML files, fi­le­names and URLs are fully com­pat­ible with the stock out­put to avoid broken links once you switch.

Ba­sic us­age

The base is con­tained in a single Py­thon script and re­lated style/tem­plate files, for ad­vanced fea­tures such as math ren­der­ing it’ll make use of in­tern­als of some m.css plu­gins. Clone the m.css Git­Hub re­pos­it­ory and look in­to the documentation/ dir­ect­ory:

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

The script re­quires Py­thon 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­pend­en­cies via pip or your dis­tri­bu­tion pack­age man­ager:

# You may need sudo here
pip3 install jinja2 Pygments

If your doc­u­ment­a­tion in­cludes math for­mu­las, in ad­di­tion you need some LaTeX dis­tri­bu­tion in­stalled. Use your dis­tri­bu­tion pack­age man­ager, for ex­ample on Ubuntu:

sudo apt install \
    texlive-base \
    texlive-latex-extra \
    texlive-fonts-extra \
    texlive-fonts-recommended

Now, in or­der to pre­serve your ori­gin­al Doxy­gen con­fig­ur­a­tion, cre­ate a new Doxyfile-mcss file next to your ori­gin­al 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­ur­a­tion from the ori­gin­al Doxyfile, dis­ables built­in Doxy­gen HTML out­put and en­ables XML out­put in­stead, with some un­needed fea­tures dis­abled for faster pro­cessing. Now run doxygen.py and point it to your Doxyfile-mcss:

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

It will run doxygen to gen­er­ate the XML out­put, pro­cesses it and gen­er­ates the HTML out­put in the con­figured out­put dir­ect­ory. After the script is done, just open gen­er­ated index.html to see the res­ult.

If you see some­thing un­ex­pec­ted or not see some­thing ex­pec­ted, check the Troubleshoot­ing sec­tion be­low.

Fea­tures

In ad­di­tion to fea­tures shared by all doc gen­er­at­ors:

  • Mod­ern, val­id, mo­bile-friendly HTM­L5 markup without table lay­outs
  • URLs fully com­pat­ible with stock Doxy­gen HTML out­put to pre­serve ex­ist­ing links
  • Fo­cused on present­ing the ac­tu­al writ­ten doc­u­ment­a­tion while re­du­cing ques­tion­able auto-gen­er­ated con­tent

Im­port­ant dif­fer­en­ces to stock HTML out­put

  • De­tailed de­scrip­tion is put first and fore­most on a page, be­fore the mem­ber list­ing
  • Files, dir­ect­or­ies and sym­bols that don’t have any doc­u­ment­a­tion are not present in the out­put at all. This is done in or­der to en­cour­age good doc­u­ment­a­tion prac­tices — hav­ing the out­put con­sist of an ac­tu­al hu­man-writ­ten doc­u­ment­a­tion in­stead of just auto­gen­er­ated lists. If you really want to have them in­cluded in the out­put, you can en­able them us­ing a de­fault-to-off SHOW_UNDOCUMENTED op­tion in conf.py (or M_SHOW_UNDOCUMENTED in the Doxyfile), but there are some tradeoffs. See Show­ing un­doc­u­men­ted sym­bols and files for more in­form­a­tion.
  • Table of con­tents is gen­er­ated 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
  • Private mem­bers and an­onym­ous namespaces are al­ways ig­nored, how­ever private vir­tu­al func­tions are lis­ted in case they are doc­u­mented. See Private vir­tu­al func­tions for more in­form­a­tion.
  • In­ner classes are lis­ted in the pub­lic/pro­tec­ted type sec­tions in­stead of be­ing lis­ted in a sep­ar­ate sec­tion ig­nor­ing their pub­lic/private status
  • Class ref­er­ences con­tain also their tem­plate spe­cific­a­tion on the linked page
  • Func­tion sig­na­tures don’t con­tain constexpr and noexcept any­more. These keywords are in­stead ad­ded as flags to the func­tion de­scrip­tion to­geth­er with virtualness, explicitity and override / final status. On the oth­er hand, im­port­ant prop­er­ties like static, const and r-value over­loads are part of func­tion sig­na­ture.
  • For bet­ter visu­al align­ment, func­tion list­ing is done us­ing the C++11 trail­ing re­turn type (auto in front) and ty­pedef list­ing is done with using). How­ever, the de­tailed doc­u­ment­a­tion is kept in the ori­gin­al form.
  • Func­tion and macro para­met­ers and enum val­ues are ver­tic­ally aligned in the mem­ber list­ing for bet­ter read­ab­il­ity
  • De­fault class tem­plate para­met­ers are not need­lessly re­peated in each mem­ber de­tailed docs
  • De­prec­a­tion mark­ers are propag­ated to mem­ber and com­pound list­ing pages and search res­ults; deleted func­tions are marked in search as well
  • In­form­a­tion about which file to #include for giv­en sym­bol is provided also for namespaces, free and re­lated func­tions, enums, ty­pedefs and vari­ables. See In­clude files for more in­form­a­tion.

In­ten­tion­ally un­sup­por­ted fea­tures

Fea­tures that I don’t see a point in be­cause they just ar­tific­ally in­flate the amount of gen­er­ated con­tent for no ad­ded value.

  • Class hier­archy graphs are ig­nored (it only in­flates the doc­u­ment­a­tion with little ad­ded value)
  • Al­pha­bet­ic­al list of sym­bols and al­pha­bet­ic­al list of all mem­bers of a class is not cre­ated (the API should be or­gan­ized in a way that makes this un­ne­ces­sary, there’s also search for this)
  • Ver­batim list­ing of parsed head­ers, “In­cludes” and “In­cluded By” lists are not present (use your IDE or Git­Hub in­stead)
  • Ini­tial­izers of defines and vari­ables are un­con­di­tion­ally ig­nored (one can al­ways look in the sources, if really needed)
  • No sec­tion with list of ex­amples or link­ing from func­tion/class doc­u­ment­a­tion to re­lated ex­ample code (he ex­ample code should be ac­com­pan­ied with cor­res­pond­ing tu­tori­al page in­stead)
  • inline func­tions are not marked as such (I see it as an un­im­port­ant im­ple­ment­a­tion de­tail)
  • The CREATE_SUBDIRS Doxy­file op­tion is not sup­por­ted. This op­tion causes Doxy­gen to scat­ter the XML files across nu­mer­ous sub­dir­ect­or­ies 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 little gain and so m.css simply 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.
  • The SHOW_NAMESPACES = NO Doxy­file op­tion is not sup­por­ted as the theme provides a much more flex­ible con­fig­ur­a­tion of what’s shown in the top navbar. See Navbar links for more in­form­a­tion.

Not yet im­ple­men­ted fea­tures

  • Click­able sym­bols in code snip­pets. Doxy­gen has quite a lot of false pos­it­ives while a lot of sym­bols stay un­matched. I need to find a way around that.
  • Doc­u­mented friend classes, structs and uni­ons. Doxy­gen is un­able to cross-link the de­clar­a­tions with the defin­i­tions.
  • Prop­er scop­ing for friend and re­lated func­tions/classes/vari­ables etc. Doxy­gen doesn’t provide any namespace scop­ing for these and at the mo­ment I have no way to de­duct that in­form­a­tion.
  • APIs lis­ted in file doc­u­ment­a­tion pages lose all namespace in­form­a­tion (and when it ap­pears in search, it’s pre­fixed with the file name in­stead of the namespace). This is due to sev­er­al bugs on Doxy­gen side, which still need to be patched (or worked around).

Con­fig­ur­a­tion

The script takes a part of the con­fig­ur­a­tion from the Doxyfile it­self, (ab)us­ing the fol­low­ing built­in op­tions:

Vari­able De­scrip­tion
@INCLUDE In­cludes in Doxyfiles are sup­por­ted
PROJECT_NAME Rendered in top navbar, foot­er fine print and page title
PROJECT_BRIEF If set, ap­pen­ded in a thin­ner font to PROJECT_NAME
PROJECT_LOGO URL of an im­age file to use as a log in the top navbar. De­fault is none.
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­ated XML
HTML_OUTPUT The out­put will be writ­ten here
TAGFILES Used to dis­cov­er what base URL to pre­pend to ex­tern­al ref­er­ences
DOT_FONTNAME Font name to use for @dot and @dotfile com­mands. To en­sure con­sist­ent 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­sist­ent look with the de­fault m.css themes, set it to 16. Doxy­gen de­fault is 10.
SHOW_INCLUDE_FILES Wheth­er to show cor­res­pond­ing #include file for classes, namespaces and namespace mem­bers. Ori­gin­ally SHOW_INCLUDE_FILES is meant to be for “a list of the files that are in­cluded by a file in the doc­u­ment­a­tion of that file” but that kind of in­form­a­tion is glar­ingly use­less in every ima­gin­able way and thus the theme is re­using it for some­thing ac­tu­ally use­ful. Doxy­gen de­fault is YES.

On top of the above, the script can take ad­di­tion­al op­tions in a way con­sist­ent with the Py­thon doc­u­ment­a­tion gen­er­at­or. The re­com­men­ded and most flex­ible way is to cre­ate a conf.py file ref­er­en­cing the ori­gin­al Doxy­file:

DOXYFILE = 'Doxyfile-mcss'

# additional options from the table below

and then pass that file to the script, in­stead of the ori­gin­al Doxy­file:

./doxygen.py path/to/your/conf.py
Vari­able De­scrip­tion
MAIN_PROJECT_URL: str If set and PROJECT_BRIEF is also set, then PROJECT_NAME in the top navbar will link to this URL and PROJECT_BRIEF to the doc­u­ment­a­tion main page, sim­il­arly as shown here.
THEME_COLOR: str Col­or for <meta name="theme-color" />, cor­res­pond­ing to the CSS style. If not set, no <meta> tag is rendered. See Theme se­lec­tion for more in­form­a­tion.
FAVICON: str Favicon URL, used to pop­u­late <link rel="icon" />. If empty, no <link> tag is rendered. Re­l­at­ive paths are searched re­l­at­ive to the con­fig file base dir and to the doxygen.py script dir as a fall­back. See Theme se­lec­tion for more in­form­a­tion.
STYLESHEETS: List[str] List of CSS files to in­clude. Re­l­at­ive paths are searched re­l­at­ive to the con­fig file base dir and to the doxygen.py script dir as a fall­back. See Theme se­lec­tion for more in­form­a­tion.
HTML_HEADER: str HTML code to put at the end of the <head> ele­ment. Use­ful for link­ing ar­bit­rary JavaS­cript code or, for ex­ample, adding <link> CSS stylesheets with ad­di­tion­al prop­er­ties and IDs that are oth­er­wise not pos­sible with just HTML_EXTRA_STYLESHEET
EXTRA_FILES: List[str] List of ex­tra files to copy (for ex­ample ad­di­tion­al CSS files that are @imported from the primary one). Re­l­at­ive paths are searched re­l­at­ive to the con­fig file base dir and to the doxygen.py script dir as a fall­back.
LINKS_NAVBAR1: List[Any] Left navbar column links. See Navbar links for more in­form­a­tion.
LINKS_NAVBAR2: List[Any] Right navbar column links. See Navbar links for more in­form­a­tion.
PAGE_HEADER: str HTML code to put at the top of every page. Use­ful for ex­ample to link to dif­fer­ent ver­sions of the same doc­u­ment­a­tion. The {filename} place­hold­er is re­placed with cur­rent file name.
FINE_PRINT: str HTML code to put in­to the foot­er. If not set, a de­fault gen­er­ic text is used. If empty, no foot­er is rendered at all. The {doxygen_version} place­hold­er is re­placed with Doxy­gen ver­sion that gen­er­ated the in­put XML files.
CLASS_INDEX_EXPAND_LEVELS How many levels of the class tree to ex­pand. 0 means only the top-level sym­bols are shown. If not set, 1 is used.
CLASS_INDEX_EXPAND_INNER Wheth­er to ex­pand in­ner types (e.g. a class in­side a class) in the sym­bol tree. If not set, False is used.
FILE_INDEX_EXPAND_LEVELS How many levels of the file tree to ex­pand. 0 means only the top-level dirs/files are shown. If not set, 1 is used.
SEARCH_DISABLED: bool Dis­able search func­tion­al­ity. If this op­tion is set, no search data is com­piled and the rendered HTML does not con­tain any search-re­lated UI or sup­port. If not set, False is used.
SEARCH_DOWNLOAD_BINARY Down­load search data as a bin­ary to save band­width and ini­tial pro­cessing time. If not set, False is used. See Search op­tions for more in­form­a­tion.
SEARCH_HELP: str HTML code to dis­play as help text on empty search popup. If not set, a de­fault mes­sage is used. Has ef­fect only if SEARCH_DISABLED is not True.
SEARCH_BASE_URL: str Base URL for OpenSearch-based search en­gine sug­ges­tions for web browsers. See Search op­tions for more in­form­a­tion. Has ef­fect only if SEARCH_DISABLED is not True.
SEARCH_EXTERNAL_URL: str URL for ex­tern­al search. The {query} place­hold­er is re­placed with ur­len­coded search string. If not set, no ex­tern­al search is offered. See Search op­tions for more in­form­a­tion. Has ef­fect only if SEARCH_DISABLED is not True.
VERSION_LABELS: bool Show the @since an­nota­tion as la­bels vis­ible in entry list­ing and de­tailed docs. De­faults to False, see Ver­sion la­bels for more in­form­a­tion.
SHOW_UNDOCUMENTED: bool In­clude un­doc­u­mented sym­bols, files and dir­ect­or­ies in the out­put. If not set, False is used. See Show­ing un­doc­u­men­ted sym­bols and files for more in­form­a­tion.
M_MATH_CACHE_FILE File to cache rendered math for­mu­las. If not set, m.math.cache file in the out­put dir­ect­ory is used. Equi­val­ent to an op­tion of the same name in the m.math plu­gin <{fi­le­name}/plu­gins/math-and-code.rst#math>.
M_CODE_FILTERS_PRE: Dict Fil­ters to ap­ply be­fore a code snip­pet is rendered. Equi­val­ent to an op­tion of the same name in the m.code plu­gin <{fi­le­name}/plu­gins/math-and-code.rst#fil­ters>. Note that due to the lim­it­a­tions of Doxy­gen markup, named fil­ters are not sup­por­ted.
M_CODE_FILTERS_POST: Dict Fil­ters to ap­ply after a code snip­pet is rendered. Equi­val­ent to an op­tion of the same name in the m.code plu­gin <{fi­le­name}/plu­gins/math-and-code.rst#fil­ters>. Note that due to the lim­it­a­tions of Doxy­gen markup, named fil­ters are not sup­por­ted.

Note that namespace, dir­ect­ory and page lists are al­ways fully ex­pan­ded as these are not ex­pec­ted to be ex­cess­ively large.

Theme se­lec­tion

By de­fault, the dark m.css theme to­geth­er with doc­u­ment­a­tion-theme-spe­cif­ic ad­di­tions is used, which cor­res­ponds to the fol­low­ing con­fig­ur­a­tion:

STYLESHEETS = [
    'https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600',
    '../css/m-dark+documentation.compiled.css'
]
THEME_COLOR = '#22272e'
FAVICON = 'favicon-dark.png'

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

STYLESHEETS = [
    '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.documentation.compiled.css'
]
THEME_COLOR = '#22272e'
FAVICON = 'favicon-dark.png'

If you prefer the light m.css theme in­stead, use the fol­low­ing con­fig­ur­a­tion (and, sim­il­arly, you can use m-light.compiled.css to­geth­er with m-light.documentation.compiled-css in place of m-light+documentation.compiled.css:

STYLESHEETS = [
    'https://fonts.googleapis.com/css?family=Libre+Baskerville:400,400i,700,700i%7CSource+Code+Pro:400,400i,600',
    '../css/m-light+documentation.compiled.css'
]
THEME_COLOR = '#cb4b16'
FAVICON = 'favicon-light.png'

See the CSS files sec­tion be­low for more in­form­a­tion about cus­tom­iz­ing the CSS files.

Search op­tions

Sym­bol search is im­ple­men­ted us­ing JavaS­cript Typed Ar­rays and does not need any serv­er-side func­tion­al­ity to per­form well — the cli­ent auto­mat­ic­ally down­loads a tightly packed bin­ary con­tain­ing search data and per­forms search dir­ectly on it.

How­ever, due to re­stric­tions of Chro­mi­um-based browsers, it’s not pos­sible to down­load data us­ing XMLHttpRequest when served from a loc­al file-sys­tem. Be­cause of that, the search de­faults to pro­du­cing a Base85-en­coded rep­res­ent­a­tion of the search bin­ary and load­ing that asyn­chron­ously as a plain JavaS­cript file. This res­ults in the search data be­ing 25% lar­ger, but since this is for serving from a loc­al filesys­tem, it’s not con­sidered a prob­lem. If your docs are ac­cessed through a serv­er (or you don’t need Chrome sup­port), en­able the SEARCH_DOWNLOAD_BINARY op­tion.

The site can provide search en­gine metadata us­ing the OpenSearch spe­cific­a­tion. On sup­por­ted browsers this means you can add the search field to search en­gines and search dir­ectly from the ad­dress bar. To en­able search en­gine metadata, point SEARCH_BASE_URL to base URL of your doc­u­ment­a­tion, for ex­ample:

SEARCH_BASE_URL = "https://doc.magnum.graphics/magnum/"

In gen­er­al, even without the above set­ting, ap­pend­ing ?q={query}#search to the URL will dir­ectly open the search popup with res­ults for {query}.

If SEARCH_EXTERNAL_URL is spe­cified, full-text search us­ing an ex­tern­al search en­gine is offered if noth­ing is found for giv­en string or if the user has JavaS­cript dis­abled. It’s re­com­men­ded to re­strict the search to a par­tic­u­lar do­main or add ad­di­tion­al keywords to the search query to fil­ter out ir­rel­ev­ant res­ults. Ex­ample, us­ing Google search en­gine and re­strict­ing the search to a sub­do­main:

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

Show­ing un­doc­u­men­ted sym­bols and files

As noted in Fea­tures, the main design de­cision of the m.css Doxy­gen theme is to re­duce the amount of use­less out­put. A plain list of un­doc­u­mented APIs also counts as use­less out­put, so by de­fault everything that’s not doc­u­mented is not shown.

In some cases, how­ever, it might be de­sir­able to show un­doc­u­mented sym­bols as well — for ex­ample when con­vert­ing an ex­ist­ing pro­ject from vanilla Doxy­gen to m.css, not all APIs might be doc­u­mented yet and thus the out­put would be in­com­plete. The SHOW_UNDOCUMENTED op­tion in conf.py (or M_SHOW_UNDOCUMENTED in the Doxyfile) un­con­di­tion­ally makes all un­doc­u­mented sym­bols, files and dir­ect­or­ies “ap­pear doc­u­mented”. Note, how­ever, that Doxy­gen it­self doesn’t al­low to link to un­doc­u­mented sym­bols and so even though the un­doc­u­mented sym­bols are present in the out­put, noth­ing is able to ref­er­ence them, caus­ing very ques­tion­able us­ab­il­ity of such ap­proach. A po­ten­tial “fix” to this is en­abling the EXTRACT_ALL Doxy­file op­tion, but that ex­poses all sym­bols, in­clud­ing private and file-loc­al ones — which, most prob­ably, is not what you want.

If you have namespaces not doc­u­mented, Doxy­gen will by put func­tion docs in­to file pages — but it doesn’t put them in­to the XML out­put, mean­ing all links to them will lead nowhere and the func­tions won’t ap­pear in search either. To fix this, en­able the XML_NS_MEMB_FILE_SCOPE Doxy­file op­tion as de­scribed in the Namespace mem­bers in file scope sec­tion be­low; if you doc­u­ment all namespaces this prob­lem will go away as well.

Con­tent

Brief and de­tailed de­scrip­tion is parsed as-is with the fol­low­ing modi­fic­a­tions:

  • Func­tion para­met­er doc­u­ment­a­tion, re­turn value doc­u­ment­a­tion, tem­plate para­met­er and ex­cep­tion doc­u­ment­a­tion is ex­trac­ted out of the text flow to al­low for more flex­ible styl­ing. It’s also re­ordered to match para­met­er or­der and warn­ings are emit­ted if there are mis­matches.
  • To make text con­tent wrap bet­ter on nar­row screens, <wbr/> tags are ad­ded after :: and _ in long sym­bols in link titles and after / in URLs.

Single-para­graph list items, func­tion para­met­er de­scrip­tion, table cell con­tent and re­turn value doc­u­ment­a­tion is stripped from the en­clos­ing <p> tag to make the out­put more com­pact. If mul­tiple para­graphs are present, noth­ing is stripped. In case of lists, they are then rendered in an in­flated form. How­ever, in or­der to achieve even spa­cing also with single-para­graph items, it’s needed use some ex­pli­cit markup. Adding <p></p> to a single-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 rendered as a fig­ure with cap­tion. It’s pos­sible af­fect width/height of the im­age us­ing the sizespec para­met­er (un­like stock Doxy­gen, which makes use of this field only for LaTeX out­put and ig­nores it for HTML out­put). The para­met­er is con­ver­ted to an in­line CSS width or height prop­erty, so the value has to con­tain the units as well:

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

Dot graphs

Grapv­iz dot graphs from the @dot and @dotfile com­mands are rendered as an in­line SVG. Graph name and the sizespec works equi­val­ently to the Im­ages and fig­ures. In or­der to be con­sist­ent with the theme, set a match­ing font name and size in the Doxy­file — these val­ues match the de­fault dark theme:

DOT_FONTNAME = Source Sans Pro
DOT_FONTSIZE = 16.0

See doc­u­ment­a­tion of the m.dot plu­gin for de­tailed in­form­a­tion about be­ha­vi­or and sup­por­ted fea­tures.

Pages, sec­tions and table of con­tents

Table of con­tents is un­con­di­tion­ally gen­er­ated for all com­pound doc­u­ment­a­tion pages and in­cludes both @section blocks in the de­tailed doc­u­ment­a­tion as well as the ref­er­ence sec­tions. If your doc­u­ment­a­tion is us­ing Mark­down-style head­ers (pre­fixed with ##, for ex­ample), the script is not able to gen­er­ate TOC entries for these. Upon en­coun­ter­ing them, tt will warn and sug­gest to use the @section com­mand in­stead.

Table of con­tents for pages is gen­er­ated only if they spe­cify @tableofcontents in their doc­u­ment­a­tion block.

Namespace mem­bers in file scope

Doxy­gen by de­fault doesn’t render namespace mem­bers for file doc­u­ment­a­tion in its XML out­put. To match the be­ha­vi­or of stock HTML out­put, en­able the XML_NS_MEMB_FILE_SCOPE Doxy­file op­tion:

XML_NS_MEMB_FILE_SCOPE = YES

Please note that APIs lis­ted in file doc­u­ment­a­tion pages lose all namespace in­form­a­tion (and when it ap­pears in search, it’s pre­fixed with the file name in­stead of the namespace). This is due to sev­er­al bugs on Doxy­gen side, which still need to be patched (or worked around).

Private vir­tu­al func­tions

Private vir­tu­al func­tions, if doc­u­mented, are shown in the out­put as well, so code­bases can prop­erly fol­low (Vir­tu­al­ity guidelines by Herb Sut­ter) To avoid also un­doc­u­mented overrides show­ing in the out­put, you may want to dis­able the INHERIT_DOCS Doxy­file op­tion (which is en­abled by de­fault). Also, please note that while privates are cur­rently un­con­di­tion­ally ex­por­ted to the XML out­put, Doxy­gen doesn’t al­low link­ing to them by de­fault and you have to en­able the EXTRACT_PRIV_VIRTUAL Doxy­file op­tion:

INHERIT_DOCS = NO
EXTRACT_PRIV_VIRTUAL = YES

In­line namespaces

inline namespaces are marked as such in class/namespace in­dex pages, namespace doc­u­ment­a­tion pages and nes­ted namespace lists. Doxy­gen ad­di­tion­ally flat­tens those, so their con­tents ap­pear in the par­ent namespace as well.

In­clude files

Doxy­gen by de­fault shows cor­res­pond­ing #includes only for classes. The m.css Doxy­gen theme shows it also for namespaces, free func­tions, enums, ty­pedefs, vari­ables and #defines. The rules are:

  • For classes, #include in­form­a­tion is al­ways shown on the top
  • If a namespace doesn’t con­tain any in­ner namespaces or classes and con­sists only of func­tions (enums, ty­pedefs, vari­ables) that are all de­clared in the same head­er file, the #include in­form­a­tion is shown only glob­ally at the top, sim­il­arly to classes
  • If a namespace con­tains in­ner classes/namespaces, or is spread over mul­tiple head­ers, the #include in­form­a­tion is shown loc­ally for each mem­ber
  • Files don’t show any in­clude in­form­a­tion, as it is known im­pli­citly
  • In case of mod­ules (grouped us­ing @defgroup), the #include info is al­ways shown loc­ally for each mem­ber. This in­cludes also #defines.
  • In case of enums, ty­pedefs, vari­ables, func­tions and defines @related to some class, these also have the #include shown in case it’s dif­fer­ent from the class include.

This fea­ture is en­abled by de­fault, dis­able SHOW_INCLUDE_FILES in the Doxy­file to hide all #include-re­lated in­form­a­tion:

SHOW_INCLUDE_FILES = NO

Code high­light­ing

Every code snip­pet should be an­not­ated with lan­guage-spe­cif­ic ex­ten­sion like in the ex­ample be­low. If not, the theme will as­sume C++ and emit a warn­ing on out­put. Lan­guage of snip­pets in­cluded via @include and re­lated com­mands is auto­de­tec­ted from fi­le­name.

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

Be­sides nat­ive Pyg­ments map­ping of file ex­ten­sions to lan­guages, there are the fol­low­ing spe­cial cases:

Fi­le­name suf­fix De­tec­ted 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 reas­on, stock Pyg­ments de­tect only .vert, .frag and .geo ex­ten­sions as GLSL.
.conf INI (key-value con­fig­ur­a­tion files)
.ansi Colored ter­min­al out­put. Use .shell-session pseudo-ex­ten­sion for simple un­colored ter­min­al out­put.
.xml-jinja Jinja tem­plates in XML markup (these don’t have any well-known ex­ten­sion oth­er­wise)
.html-jinja Jinja tem­plates in HTML markup (these don’t have any well-known ex­ten­sion oth­er­wise)
.jinja Jinja tem­plates (these don’t have any well-known ex­ten­sion oth­er­wise)

The theme has ex­per­i­ment­al 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­ited from sur­round­ing para­graphs with an empty line is con­sidered as block.
  • Code that is com­ing from @include, @snippet and re­lated com­mands that paste ex­tern­al file con­tent is al­ways con­sidered as block.
  • Code that is com­ing from @code and is not alone in a para­graph is con­sidered as in­line.
  • For com­pat­ib­il­ity reas­ons, if code that is de­tec­ted as in­line con­sists of more than one line, it’s rendered as code block and a warn­ing is prin­ted to out­put.

In­line high­lighted code is writ­ten also 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 verb­ose, it’s ad­vised to con­fig­ure some ali­ases in your Doxyfile-mcss. For ex­ample, you can con­fig­ure an ali­as for gen­er­al in­line code snip­pets and short­er ver­sions for com­monly 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 simply as:

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

If you need to pre­serve com­pat­ib­il­ity with stock Doxy­gen HTML out­put (be­cause it renders all @code sec­tions as blocks), use the fol­low­ing fall­back ali­ases in the ori­gin­al Doxyfile:

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

Theme-spe­cif­ic com­mands

It’s pos­sible to in­sert cus­tom m.css classes 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­ib­il­ity with stock Doxy­gen HTML out­put, just make the ali­ases empty in your ori­gin­al Doxyfile. Note that you can re­name the ali­ases how­ever 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­sible to add CSS classes to the im­me­di­ately fol­low­ing para­graph, im­age, table, list or math for­mula block. When used be­fore a block such as @par, @note, @see or @xrefitem, the CSS class fully over­rides the block styl­ing. By de­fault .m-note with some col­or and <h4> is used, with @m_class be­fore it get <h3> for the title and you can turn it in­to a block, for ex­ample:

/**
@m_class{m-block m-success}

@par Third-party license info
    This utility depends on the [Magnum engine](https://magnum.graphics).
    It's licensed under MIT, so all you need to do is mention it in the
    credits of your commercial app.
*/

When used in­line, it af­fects the im­me­di­ately fol­low­ing em­phas­is, strong text, link or in­line math for­mula. Ex­ample 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­mula:

e^{i \pi} + 1 = 0

Use the Shift key.

The built­in @parblock com­mand can be com­bined with @m_class to wrap a block of HTML code in a <div> and add CSS classes to it. With @m_div and @m_span it’s pos­sible to wrap in­di­vidu­al para­graphs or in­line text in <div> / <span> and add CSS classes to them without any ex­tra ele­ments be­ing ad­ded. Ex­ample us­age and cor­res­pond­ing rendered HTML out­put:

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

Centered.
@endparblock

@m_div{m-button m-primary} <a href="https://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­sible to com­bine @par with @parblock to cre­ate blocks, notes and oth­er m.css com­pon­ents with ar­bit­rary con­tents. The @par com­mand visu­als can be fully over­riden by put­ting @m_class in front, the @parblock after will en­sure everything will be­long in­side. A bit re­curs­ive ex­ample:

/**
@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­il­ar 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 rendered page to con­tain a link to pre­vi­ous, par­ent and next page ac­cord­ing to defined page or­der.

The @m_examplenavigation com­mand is able to put bread­crumb nav­ig­a­tion to par­ent page(s) of @example list­ings in or­der to make it easi­er for users to re­turn back from ex­ample source code to a tu­tori­al page, for ex­ample. When used in com­bin­a­tion with @m_footernavigation, nav­ig­a­tion to par­ent page and to prev/next file of the same ex­ample 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­ample (used to build the bread­crumb and foot­er nav­ig­a­tion), second is ex­ample path pre­fix (which is then stripped from page title and is also used to dis­cov­er which ex­ample files be­long to­geth­er). Ex­ample us­age — the @m_examplenavigation and @m_footernavigation com­mands are simply ap­pen­ded 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 keywords to giv­en doc­u­mented sym­bols. Use @m_keywords to enter whitespace-sep­ar­ated list of keywords. The @m_enum_values_as_keywords com­mand will add ini­tial­izers of giv­en enum val­ues as keywords for each cor­res­pond­ing value, it’s ig­nored when not used in enum de­scrip­tion block. In the fol­low­ing ex­ample, an OpenGL wrap­per API adds GL API names as keywords for easi­er dis­cov­er­ab­il­ity, so e.g. the Texture2D::setStorage() func­tion is also found when typ­ing glTexStorage2D() in­to the search field, or the Renderer::Feature::DepthTest enum value 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 enter a keyword con­tain­ing spaces, the op­tion­al second and third para­met­er al­low you to spe­cify a dif­fer­ent title and suf­fix length. Ex­ample us­age — in the first case be­low, the page will be dis­cov­er­able both us­ing its primary title and us­ing TCB spline sup­port, in the second and third case the two over­loads of the lerp() func­tion are dis­cov­er­able also via mix(), dis­play­ing either GLSL mix() or GLSL mix(gen­Type, gen­Type, float) in the search res­ults. The last para­met­er is suf­fix length, needed to cor­rectly hig­light the mix sub­string when there are ad­di­tion­al char­ac­ters at the end of the title. If not spe­cified, it de­faults to 0, mean­ing the search string is a suf­fix of the title.

/**
 * @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);

Ver­sion la­bels

By de­fault, to keep com­pat­ib­il­ity with ex­ist­ing con­tent, the @since block is rendered as a note dir­ectly in the text flow. If you en­able the M_SINCE_BADGES op­tion, con­tent of the @since block is ex­pec­ted to be a single la­bel that can op­tion­ally link to a changelog entry. The la­bel is then placed vis­ibly next to giv­en entry and de­tailed de­scrip­tion as well as all list­ings. Ad­di­tion­ally, if @since is fol­lowed by @deprecated, it adds ver­sion info to the de­prec­a­tion no­tice (in­stead of de­not­ing when giv­en fea­ture was ad­ded) — in this case it ex­pects just a tex­tu­al info, without any la­bel styl­ing. Re­com­men­ded use is in com­bin­a­tion with an ali­as that takes care of the la­bel ren­der­ing and For ex­ample (the @m_class is the same as de­scribed in Theme-spe­cif­ic com­mands above):

ALIASES = \
    "m_class{1}=@xmlonly<mcss:class xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\" />@endxmlonly" \
    "m_since{2}=@since @m_class{m-label m-success m-flat} @ref changelog-\1-\2 \"since v\1.\2\"" \
    "m_deprecated_since{2}=@since deprecated in v\1.\2 @deprecated"

in the Doxy­file, and the fol­low­ing in conf.py:

VERSION_LABELS = True

With the above con­fig­ur­a­tion, the fol­low­ing markup will render a since v1.3 la­bel lead­ing to a page named changelog-1-3 next to both func­tion entry and de­tailed docs in the first case, and a de­prec­ated since v1.3 la­bel in the second case:

/**
@brief Fast inverse square root
@m_since{1,3}

Faster than `1.0f/sqrt(a)`.
*/
float fastinvsqrt(float a);

/**
@brief Slow inverse square root

Attempts to figure out the value by a binary search.
@m_deprecated_since{1,3} Use @ref fastinvsqrt() instead.
*/
float slowinvsqrt(float a);

Com­mand-line op­tions

./doxygen.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]
             config

Ar­gu­ments:

  • config — where the Doxy­file or conf.py is

Op­tions:

  • -h, --help — show this help mes­sage and exit
  • --templates TEMPLATES — tem­plate dir­ect­ory. De­faults to the templates/doxygen/ sub­dir­ect­ory if not set.
  • --wildcard WILDCARD — only pro­cess files match­ing the wild­card. Use­ful for de­bug­ging to speed up / re­strict the pro­cessing 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­ig­a­tion page tem­plates sec­tion be­low for more in­form­a­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­ated XML out­put.
  • --search-no-subtree-merging — don’t op­tim­ize search data size by mer­ging sub­trees
  • --search-no-lookahead-barriers — don’t in­sert search looka­head bar­ri­ers that im­prove search res­ult rel­ev­ance
  • --search-no-prefix-merging — don’t merge search res­ult pre­fixes
  • --sort-globbed-files — sort globbed files for bet­ter re­pro­du­cib­il­ity
  • --debug — verb­ose log­ging out­put. Use­ful for de­bug­ging.

Troubleshoot­ing

Gen­er­ated out­put is (mostly) empty

As stated in the Fea­tures sec­tion above; files, dir­ect­or­ies and sym­bols with no doc­u­ment­a­tion are not present in the out­put at all. In par­tic­u­lar, when all your sources are un­der a sub­dir­ect­ory and/or a namespace and that sub­dir­ect­ory / namespace is not doc­u­mented, the file / sym­bol tree will not show any­thing.

A simple @brief entry is enough to fix this. For ex­ample, if you have a MorningCoffee::CleanCup class that’s avail­able from #include <MorningCoffee/CleanCup.h>, these doc­u­ment­a­tion blocks are enough to have the dir­ect­ory, file, namespace and also 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 doxygen.py with the --debug op­tion. and look for entries that look like be­low. Be­cause there are many false pos­it­ives, this in­form­a­tion is not present in the non-verb­ose out­put.

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

Al­tern­at­ively, there’s a pos­sib­il­ity to just show everything, how­ever that may in­clude also things you don’t want to have shown. See Show­ing un­doc­u­men­ted sym­bols and files for more in­form­a­tion.

Out­put is not styled

If your Doxyfile con­tains a non-empty HTML_EXTRA_STYLESHEET op­tion, m.css will use CSS files from there in­stead of the built­in ones. Either over­ride it to an empty value in your Doxyfile-mcss or spe­cify prop­er CSS files ex­pli­citly as men­tioned in the Theme se­lec­tion sec­tion.

Gen­er­at­ing takes too long, crashes, as­serts or gen­er­ally fails

The XML out­put gen­er­ated by Doxy­gen is un­der­spe­cified and un­ne­ces­sar­ily com­plex, so it might very well hap­pen that your doc­u­ment­a­tion trig­gers some un­tested code path. The script is de­signed to fail early and hard in­stead of si­lently con­tinu­ing and pro­du­cing 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­mula ren­der­ing is not batched and takes very long, as LaTeX is star­ted sep­ar­ately for every oc­cur­rence. Help in this area is wel­come.
  • Try with a freshly gen­er­ated Doxyfile. If it stops hap­pen­ing, the prob­lem might be re­lated to some con­fig­ur­a­tion op­tion (but maybe also an ali­as or pre­pro­cessor #define that’s not defined any­more)
  • m.css cur­rently ex­pects only C++ in­put. If you have Py­thon or some oth­er lan­guage on in­put, it will get very con­fused very fast. This can be also caused by a file be­ing in­cluded 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­ev­ant info (es­pe­cially Doxy­gen ver­sion). Or ask in the Git­ter chat. If I’m not able to provide a fix right away, there’s a great chance I’ve already seen such prob­lem and can sug­gest a work­around at least.

Cus­tom­iz­ing the tem­plate

The rest of the doc­u­ment­a­tion ex­plains how to cus­tom­ize the built­in tem­plate to bet­ter suit your needs. Each doc­u­ment­a­tion file is gen­er­ated from one of the tem­plate files that are bundled with the script. How­ever, it’s pos­sible to provide your own Jin­ja2 tem­plate files for cus­tom­ized ex­per­i­ence as well as modi­fy the CSS styl­ing.

CSS files

By de­fault, com­piled CSS files are used to re­duce amount of HT­TP re­quests and band­width needed for view­ing the doc­u­ment­a­tion. How­ever, for easi­er cus­tom­iz­a­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 res­ult­ing HTML markup, while HTML_EXTRA_FILES lists the in­dir­ectly ref­er­enced files that need to be copied to the out­put as well. Be­low is an ex­ample con­fig­ur­a­tion cor­res­pond­ing to the dark theme:

STYLESHEETS = [
    '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-documentation.css'
]
EXTRA_FILES = [
    '../css/m-theme-dark.css',
    '../css/m-grid.css',
    '../css/m-components.css',
    '../css/m-layout.css',
    '../css/pygments-dark.css',
    '../css/pygments-console.css'
]
THEME_COLOR = '#22272e'

After mak­ing de­sired changes to the source files, it’s pos­sible to post­pro­cess them back to the com­piled ver­sion us­ing the postprocess.py util­ity as ex­plained in the CSS themes doc­u­ment­a­tion. In case of the dark theme, the m-dark+documentation.compiled.css and m-dark.documentation.compiled.css files are pro­duced like this:

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

Com­pound doc­u­ment­a­tion tem­plate

For com­pound doc­u­ment­a­tion one out­put HTML file cor­res­ponds to one in­put XML file and there are some nam­ing con­ven­tions im­posed by Doxy­gen.

Fi­le­name Use
class.html Class doc­u­ment­a­tion, read from class*.xml and saved as class*.html
dir.html Dir­ect­ory doc­u­ment­a­tion, read from dir_*.xml and saved as dir_*.html
example.html Ex­ample code list­ing, read from *-example.xml and saved as *-example.html
file.html File doc­u­ment­a­tion, read from *.xml and saved as *.html
namespace.html Namespace doc­u­ment­a­tion, read fron namespace*.xml and saved as namespace*.html
group.html Mod­ule doc­u­ment­a­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­ment­a­tion, read from struct*.xml and saved as struct*.html
union.html Uni­on doc­u­ment­a­tion, read from union*.xml and saved as union*.html

Each tem­plate is passed a sub­set of the Doxyfile and conf.py con­fig­ur­a­tion val­ues from the Con­fig­ur­a­tion tables. Most val­ues are provided as-is de­pend­ing on their type, so either strings, booleans, or lists of strings. The ex­cep­tions are:

  • The LINKS_NAVBAR1 and LINKS_NAVBAR2 are pro­cessed to tuples in a form (html, title, url, id, sub) where either html is a full HTML code for the link and title, url id is empty; or html is None, title and url is a link title and URL and id is com­pound ID (to use for high­light­ing act­ive menu item). The last item, sub is a list op­tion­ally con­tain­ing sub-menu items. The sub-menu items are in a sim­il­arly formed tuple, (html, title, url, id).
  • The FAVICON is con­ver­ted to a tuple of (url, type) where url is the favicon URL and type is favicon MIME type to pop­u­late the type at­trib­ute 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­ated giv­en XML file

In ad­di­tion to built­in Jin­ja2 fil­ters, the basename_or_url fil­ter re­turns either a base­name of file path, if the path is re­l­at­ive; or a full URL, if the ar­gu­ment is an ab­so­lute URL. It’s use­ful in cases like this:

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

The ac­tu­al page con­tents are provided in a compound ob­ject, which has the fol­low­ing prop­er­ties. All ex­posed data are meant to be pas­ted dir­ectly to the HTML code without any es­cap­ing.

Prop­erty 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­ally cor­res­pond­ing to out­put file name
compound.url Com­pound URL (or where this file will be saved)
compound.include Cor­res­pond­ing #include state­ment to use giv­en com­pound. Set only for classes or namespaces that are all defined in a single file. See In­clude prop­er­ties for de­tails.
compound.name Com­pound name
compound.templates Tem­plate spe­cific­a­tion. Set only for classes. See Tem­plate prop­er­ties for de­tails.
compound.has_template_details If there is a de­tailed doc­u­ment­a­tion of tem­plate para­met­ers
compound.sections Sec­tions of de­tailed de­scrip­tion. See Nav­ig­a­tion prop­er­ties for de­tails.
compound.footer_navigation Foot­er nav­ig­a­tion of a page. See Nav­ig­a­tion prop­er­ties for de­tails.
compound.brief Brief de­scrip­tion. Can be empty. 1
compound.is_inline Wheth­er the namespace is inline. Set only for namespaces.
compound.is_final Wheth­er the class is final. Set only for classes.
compound.deprecated De­prec­a­tion status 7
compound.since Since which ver­sion the com­pound is avail­able 8
compound.description De­tailed de­scrip­tion. Can be empty. 2
compound.modules List of sub­mod­ules in this com­pound. Set only for mod­ules. See Mod­ule prop­er­ties for de­tails.
compound.dirs List of dir­ect­or­ies in this com­pound. Set only for dir­ect­or­ies. See Dir­ect­ory prop­er­ties for de­tails.
compound.files List of files in this com­pound. Set only for dir­ect­or­ies and files. See File prop­er­ties for de­tails.
compound.namespaces List of namespaces in this com­pound. Set only for files and namespaces. See Namespace prop­er­ties for de­tails.
compound.classes List of classes in this com­pound. Set only for files and namespaces. See Class prop­er­ties for de­tails.
compound.base_classes List of base classes in this com­pound. Set only for classes. See Class prop­er­ties for de­tails.
compound.derived_classes List of de­rived classes in this com­pound. Set only for classes. See Class prop­er­ties for de­tails.
compound.enums List of enums in this com­pound. Set only for files and namespaces. See Enum prop­er­ties for de­tails.
compound.typedefs List of ty­pedefs in this com­pound. Set only for files and namespaces. See Ty­ped­ef prop­er­ties for de­tails.
compound.funcs List of func­tions in this com­pound. Set only for files and namespaces. See Func­tion prop­er­ties for de­tails.
compound.vars List of vari­ables in this com­pound. Set only for files and namespaces. See Vari­able prop­er­ties for de­tails.
compound.defines List of defines in this com­pound. Set only for files. See Define prop­er­ties for de­tails.
compound.public_types List of pub­lic types. Set only for classes. See Type prop­er­ties for de­tails.
compound.public_static_funcs List of pub­lic stat­ic func­tions. Set only for classes. See Func­tion prop­er­ties for de­tails.
compound.public_funcs List of pub­lic func­tions. Set only for classes. See Func­tion prop­er­ties for de­tails.
compound.signals List of Qt sig­nals. Set only for classes. See Func­tion prop­er­ties for de­tails.
compound.public_slots List of pub­lic Qt slots. Set only for classes. See Func­tion prop­er­ties for de­tails.
compound.public_static_vars List of pub­lic stat­ic vari­ables. Set only for classes. See Vari­able prop­er­ties for de­tails.
compound.public_vars List of pub­lic vari­ables. Set only for classes. See Vari­able prop­er­ties for de­tails.
compound.protected_types List of pro­tec­ted types. Set only for classes. See Type prop­er­ties for de­tails.
compound.protected_static_funcs List of pro­tec­ted stat­ic func­tions. Set only for classes. See Func­tion prop­er­ties for de­tails.
compound.protected_funcs List of pro­tec­ted func­tions. Set only for classes. See Func­tion prop­er­ties for de­tails.
compound.protected_slots List of pro­tec­ted Qt slots. Set only for classes. See Func­tion prop­er­ties for de­tails.
compound.protected_static_vars List of pro­tec­ted stat­ic vari­ables. Set only for classes. See Vari­able prop­er­ties for de­tails.
compound.protected_vars List of pro­tec­ted vari­ables. Set only for classes. See Vari­able prop­er­ties for de­tails.
compound.private_funcs List of doc­u­mented private vir­tu­al func­tions. Set only for classes. See Func­tion prop­er­ties for de­tails.
compound.private_slots List of doc­u­mented private vir­tu­al Qt slots. Set only for classes. See Func­tion prop­er­ties for de­tails.
compound.friend_funcs List of doc­u­mented friend func­tions. Set only for classes. See Func­tion prop­er­ties for de­tails.
compound.related List of re­lated non-mem­ber sym­bols. Set only for classes. See Re­lated prop­er­ties for de­tails.
compound.groups List of user-defined 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 ty­pedef 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 define with full de­scrip­tion block 5
compound.breadcrumb List of (title, URL) tuples for bread­crumb nav­ig­a­tion. Set only for classes, dir­ect­or­ies, files, namespaces and pages.
compound.prefix_wbr Fully-qual­i­fied sym­bol pre­fix for giv­en com­pound with trail­ing :: with <wbr/> tag be­fore every ::. Set only for classes, namespaces, structs and uni­ons; on tem­plated classes con­tains also the list of tem­plate para­met­er names.

In­clude prop­er­ties

The compound.include prop­erty is a tuple of (name, URL) where name is the in­clude name (to­geth­er with angle brack­ets, quotes or a macro name) and URL is a URL point­ing to the cor­res­pond­ing head­er doc­u­ment­a­tion file. This prop­erty is present only if the cor­res­pond­ing head­er doc­u­ment­a­tion is present. This prop­erty is present for classes; namespaces have it only when all doc­u­mented namespace con­tents are defined in a single file. For mod­ules and namespaces spread over mul­tiple files this prop­erty is presen­ted sep­ar­ately for each enum, ty­pedef, func­tion, vari­able or define in­side giv­en mod­ule or namespace. Dir­ect­or­ies, files and file mem­bers don’t provide this prop­erty, since in that case the map­ping to a cor­res­pond­ing #include file is known im­pli­citly.

Mod­ule prop­er­ties

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

Prop­erty 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 empty. 1
module.deprecated De­prec­a­tion status 7
module.since Since which ver­sion the mod­ule is avail­able 8

Dir­ect­ory prop­er­ties

The compound.dirs prop­erty con­tains a list of dir­ect­or­ies, where every item has the fol­low­ing prop­er­ties:

Prop­erty De­scrip­tion
dir.url URL of the file con­tain­ing de­tailed dir­ect­ory docs
dir.name Dir­ect­ory name (just the leaf)
dir.brief Brief de­scrip­tion. Can be empty. 1
dir.deprecated De­prec­a­tion status 7
dir.since Since which ver­sion the dir­ect­ory is avail­able 8

File prop­er­ties

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

Prop­erty 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 empty. 1
file.deprecated De­prec­a­tion status 7
file.since Since which ver­sion the file is avail­able 8

Namespace prop­er­ties

The compound.namespaces prop­erty con­tains a list of namespaces, where every item has the fol­low­ing prop­er­ties:

Prop­erty De­scrip­tion
namespace.url URL of the file con­tain­ing de­tailed namespace docs
namespace.name Namespace name. Fully qual­i­fied in case it’s in a file doc­u­ment­a­tion, just the leaf name if in a namespace doc­u­ment­a­tion.
namespace.brief Brief de­scrip­tion. Can be empty. 1
namespace.deprecated De­prec­a­tion status 7
namespace.since Since which ver­sion the namespace is avail­able 8
namespace.is_inline Wheth­er this is an inline namespace

Class prop­er­ties

The compound.classes prop­erty con­tains a list of classes, where every item has the fol­low­ing prop­er­ties:

Prop­erty 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. Fully qual­i­fied in case it’s in a file doc­u­ment­a­tion, just the leaf name if in a namespace doc­u­ment­a­tion.
class.templates Tem­plate spe­cific­a­tion. See Tem­plate prop­er­ties for de­tails.
class.brief Brief de­scrip­tion. Can be empty. 1
class.deprecated De­prec­a­tion status 7
class.since Since which ver­sion the class is avail­able 8
class.is_protected Wheth­er this is a pro­tec­ted base class. Set only for base classes.
class.is_virtual Wheth­er this is a vir­tu­al base class or a vir­tu­ally de­rived class. Set only for base / de­rived classes.
class.is_final Wheth­er this is a fi­nal de­rived class. Set only for de­rived classes.

Enum prop­er­ties

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

Prop­erty De­scrip­tion
enum.base_url Base URL of file con­tain­ing de­tailed de­scrip­tion 3
enum.include Cor­res­pond­ing #include to get the enum defin­i­tion. Present only for enums in­side mod­ules or in­side namespaces that are spread over mul­tiple files. See In­clude prop­er­ties for more in­form­a­tion.
enum.id Iden­ti­fi­er hash 3
enum.type Enum type or empty if im­pli­citly typed 6
enum.is_strong If the enum is strong
enum.name Enum name 4
enum.brief Brief de­scrip­tion. Can be empty. 1
enum.description De­tailed de­scrip­tion. Can be empty. 2
enum.has_details If there is enough con­tent for the full de­scrip­tion block 5
enum.deprecated De­prec­a­tion status 7
enum.since Since which ver­sion the enum is avail­able 8
enum.is_protected If the enum is protected. Set only for mem­ber types.
enum.values List of enum val­ues
enum.has_value_details If the enum val­ues have de­scrip­tion

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

Prop­erty 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 Value name 4
value.initializer Value ini­tial­izer. Can be empty. 1
value.deprecated De­prec­a­tion status 7
value.since Since which ver­sion the value is avail­able 8
value.brief Brief de­scrip­tion. Can be empty. 1
value.description De­tailed de­scrip­tion. Can be empty. 2

Ty­ped­ef prop­er­ties

The compound.typedefs prop­erty con­tains a list of ty­pedefs, where every item has the fol­low­ing prop­er­ties:

Prop­erty De­scrip­tion
typedef.base_url Base URL of file con­tain­ing de­tailed de­scrip­tion 3
typedef.include Cor­res­pond­ing #include to get the ty­pedef de­clar­a­tion. Present only for ty­pedefs in­side mod­ules or in­side namespaces that are spread over mul­tiple files. See In­clude prop­er­ties for more in­form­a­tion.
typedef.id Iden­ti­fi­er hash 3
typedef.is_using Wheth­er it is a typedef or an using
typedef.type Ty­pedef type, or what all goes be­fore the name for func­tion point­er ty­pedefs 6
typedef.args Ty­pedef ar­gu­ments, or what all goes after the name for func­tion point­er ty­pedefs 6
typedef.name Ty­pedef name 4
typedef.templates Tem­plate spe­cific­a­tion. Set only in case of using. . See Tem­plate prop­er­ties for de­tails.
typedef.has_template_details If tem­plate para­met­ers have de­scrip­tion
typedef.brief Brief de­scrip­tion. Can be empty. 1
typedef.deprecated De­prec­a­tion status 7
typedef.since Since which ver­sion the ty­pedef is avail­able 8
typedef.description De­tailed de­scrip­tion. Can be empty. 2
typedef.has_details If there is enough con­tent for the full de­scrip­tion block 4
typedef.is_protected If the ty­pedef is protected. Set only 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 every item has the fol­low­ing prop­er­ties:

Prop­erty De­scrip­tion
func.base_url Base URL of file con­tain­ing de­tailed de­scrip­tion 3
func.include Cor­res­pond­ing #include to get the func­tion de­clar­a­tion. Present only for func­tions in­side mod­ules or in­side namespaces that are spread over mul­tiple files. See In­clude prop­er­ties for more in­form­a­tion.
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 spe­cific­a­tion. See Tem­plate prop­er­ties for de­tails.
func.has_template_details If tem­plate para­met­ers have de­scrip­tion
func.params List of func­tion para­met­ers. See be­low for de­tails.
func.has_param_details If func­tion para­met­ers have de­scrip­tion
func.return_value Re­turn value de­scrip­tion. Can be empty.
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 empty. 1
func.description De­tailed de­scrip­tion. Can be empty. 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 keywords such as static. In­form­a­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 keywords such as const and r-value over­loads. In­form­a­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.deprecated De­prec­a­tion status 7
func.since Since which ver­sion the func­tion is avail­able 8
func.is_protected If the func­tion is protected. Set only for mem­ber func­tions.
func.is_private If the func­tion is private. Set only for mem­ber func­tions.
func.is_explicit If the func­tion is explicit. Set only for mem­ber func­tions.
func.is_virtual If the func­tion is virtual (or pure vir­tu­al). Set only for mem­ber func­tions.
func.is_pure_virtual If the func­tion is pure virtual. Set only for mem­ber func­tions.
func.is_override If the func­tion is an override. Set only for mem­ber func­tions.
func.is_final If the func­tion is a final override. Set only for mem­ber func­tions.
func.is_noexcept If the func­tion is noexcept (even con­di­tion­ally)
func.is_conditional_noexcept If the func­tion is con­di­tion­ally 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 only for mem­ber func­tions.
func.is_slot If the func­tion is a Qt slot. Set only for mem­ber func­tions.

The func.params is a list of func­tion para­met­ers and their de­scrip­tion. Each item has the fol­low­ing prop­er­ties:

Prop­erty De­scrip­tion
param.name Para­met­er name (if not an­onym­ous)
param.type Para­met­er type, to­geth­er with ar­ray spe­cific­a­tion 6
param.type_name Para­met­er type, to­geth­er with name and ar­ray spe­cific­a­tion 6
param.default De­fault para­met­er value, if any 6
param.description Op­tion­al para­met­er de­scrip­tion. If set, func.has_param_details is set as well.
param.direction Para­met­er dir­ec­tion. One of 'in', 'out', 'inout' or '' if un­spe­cified.

The func.return_values prop­erty is a list of re­turn val­ues and their de­scrip­tion (in con­tract to func.return_value, which is just a single de­scrip­tion). Each item is a tuple of (value, description). Can be empty, it can also hap­pen that both func.return_value and func.return_values are re­sent. Sim­il­arly, the func.exceptions prop­erty is a list of (type, description) tuples.

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 every item has the fol­low­ing prop­er­ties:

Prop­erty De­scrip­tion
var.base_url Base URL of file con­tain­ing de­tailed de­scrip­tion 3
var.include Cor­res­pond­ing #include to get the vari­able de­clar­a­tion. Present only for vari­ables in­side mod­ules or in­side namespaces that are spread over mul­tiple files. See In­clude prop­er­ties for more in­form­a­tion.
var.id Iden­ti­fi­er hash 3
var.type Vari­able type 6
var.name Vari­able name 4
var.templates Tem­plate spe­cific­a­tion for C++14 vari­able tem­plates. See Tem­plate prop­er­ties for de­tails.
var.has_template_details If tem­plate para­met­ers have de­scrip­tion
var.brief Brief de­scrip­tion. Can be empty. 1
var.description De­tailed de­scrip­tion. Can be empty. 2
var.has_details If there is enough con­tent for the full de­scrip­tion block 5
var.deprecated De­prec­a­tion status 7
var.since Since which ver­sion the vari­able is avail­able 8
var.is_static If the vari­able is static. Set only for mem­ber vari­ables.
var.is_protected If the vari­able is protected. Set only for mem­ber vari­ables.
var.is_constexpr If the vari­able is constexpr

Define prop­er­ties

The compound.defines prop­erty con­tains a list of defines, where every item has the fol­low­ing prop­er­ties:

Prop­erty De­scrip­tion
define.include Cor­res­pond­ing #include to get the define defin­i­tion. Present only for defines in­side mod­ules, since oth­er­wise the define is doc­u­mented in­side a file docs and the cor­res­pond­ing in­clude is known im­pli­citly. See In­clude prop­er­ties for more in­form­a­tion.
define.id Iden­ti­fi­er hash 3
define.name Define name
define.params List of macro para­met­er names. See be­low for de­tails.
define.has_param_details If define para­met­ers have de­scrip­tion
define.return_value Re­turn value de­scrip­tion. Can be empty.
define.brief Brief de­scrip­tion. Can be empty. 1
define.description De­tailed de­scrip­tion. Can be empty. 2
define.deprecated De­prec­a­tion status 7
define.since Since which ver­sion the define is avail­able 8
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 tuple 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­big­u­ate between pre­pro­cessor mac­ros and vari­ables in your code.

Type prop­er­ties

For classes, the compound.public_types and compound.protected_types con­tains a list of (kind, type) tuples, where kind is one of 'class', 'enum' or 'typedef' and type is a cor­res­pond­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 either None if giv­en sym­bol is a full tem­plate spe­cial­iz­a­tion or a list of tem­plate para­met­ers, where every item has the fol­low­ing prop­er­ties:

Prop­erty De­scrip­tion
template.type Tem­plate para­met­er type (class, typename or a type)
template.name Tem­plate para­met­er name
template.default Tem­plate de­fault value. Can be empty.
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 user-defined groups. Each item has the fol­low­ing prop­er­ties:

Prop­erty 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 tuple of (kind, member), where kind is one of 'namespace', 'class', 'enum', 'typedef', 'func', 'var' or 'define' and member is a cor­res­pond­ing type of ob­ject de­scribed above.