Doxygen theme

A mod­ern, mo­bile-friend­ly drop-in re­place­ment for the stock Doxy­gen HTML out­put, gen­er­at­ed from Doxy­gen-pro­duced XML files. Gen­er­at­ed 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

Ev­ery­thing you need apart from Doxy­gen it­self is a Python script and a bunch of tem­plate files. You can get that by cloning the m.css GitHub re­pos­i­to­ry and look­ing 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:

pip 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.

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
  • Us­es Pyg­ments for bet­ter code high­light­ing

Im­por­tant dif­fer­ences 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
  • 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

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)
  • 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)
  • Un­doc­u­ment­ed or pri­vate mem­bers and con­tent of anony­mous names­paces are ig­nored (if things are un­doc­u­ment­ed or in­ten­tion­al­ly hid­den, why put them in the doc­u­men­ta­tion)
  • Brief de­scrip­tion for enum val­ues is ig­nored (on­ly the de­tailed de­scrip­tion is used, as the brief de­scrip­tion was nev­er used any­where else than next to the de­tailed de­scrip­tion)
  • Ini­tial­iz­ers of de­fines and vari­ables are un­con­di­tion­al­ly ig­nored (look in the sources, if you re­al­ly need that)
  • 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)

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

  • Code search. I want to pro­vide some­thing that’s ac­tu­al­ly us­able to re­place the ter­ri­bly slow stock client-side search, but I’m not there yet.
  • 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.

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 al­so searched rel­a­tive to the dox2html5.py script. See be­low 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 al­so searched rel­a­tive to the dox2html5.py script.

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 be­low for more in­for­ma­tion.
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. 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_SHOW_DOXYGEN_VERSION Show Doxy­gen ver­sion in the foot­er. If not set, YES is used; use­ful to dis­able for out­put ver­i­fi­ca­tion.

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.

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

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

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

Com­mand-line op­tions

./dox2html5.py [-h] [--templates TEMPLATES] [--wildcard WILDCARD]
               [--index-pages INDEX_PAGES [INDEX_PAGES ...]]
               [--no-doxygen] [--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, 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.
  • --debug — ver­bose de­bug out­put. Use­ful for de­bug­ging.

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 and tem­plate pa­ram­e­ter 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.

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.

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.

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"

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="

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. Ex­am­ple us­age and cor­re­spond­ing ren­dered HTML out­put:

/**
@div{m-note m-dim m-text-center} This paragraph is rendered in a dim
note, centered. @enddiv

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

This text con­tains a green word.

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:

/** See the red @m_class{m-danger} @f$ \Sigma @f$ character. */

See the red LaTeX Math \Sigma char­ac­ter.

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.

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
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 above ta­ble 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 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', '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.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.description De­tailed de­scrip­tion. Can be emp­ty. 2
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.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.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_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.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.
compound.save_as File­name in­clud­ing ex­ten­sion where the re­sult will be saved

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

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

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

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

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.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_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.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.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.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.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.protected_static_funcs, compound.protected_funcs, compound.private_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.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.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_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

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 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.

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.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_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.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.
1(1,2,3,4,5,6,7,8,9,10,11)
i.brief is a sin­gle-line para­graph with­out the en­clos­ing <p> el­e­ment, ren­dered as HTML. Can be emp­ty in case of func­tion over­loads.
2(1,2,3,4,5,6,7,8)
i.description is HTML code with the full de­scrip­tion, con­tain­ing para­graphs, notes, code blocks, im­ages etc. Can be emp­ty in case just the brief de­scrip­tion is present.
3(1,2,3,4,5,6,7)
i.id is a hash used to link to the mem­ber on the page, usu­al­ly ap­pear­ing af­ter # in page URL
4(1,2,3,4,5,6)
i.name is just the mem­ber name, not qual­i­fied. Prepend compound.prefix_wbr to it to get the ful­ly qual­i­fied name.
5(1,2,3,4,5,6,7,8,9)
compound.has_*_details and i.has_details are True if there is de­tailed de­scrip­tion, func­tion/tem­plate/macro pa­ram­e­ter doc­u­men­ta­tion or enum val­ue list­ing that makes it worth to ren­der the full de­scrip­tion block. If False, the mem­ber should be in­clud­ed on­ly in the brief list­ing on top of the page to avoid un­nec­es­sary rep­e­ti­tion.
6(1,2,3,4,5,6,7)
i.type and param.default is ren­dered as HTML and usu­al­ly con­tains links to re­lat­ed doc­u­men­ta­tion