Doc generators » Doxygen C++ theme

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

The theme is de­lib­er­ately only for C and C++. See the Py­thon doc­u­ment­a­tion gen­er­at­or for a ded­ic­ated tool hand­ling Py­thon. Oth­er lan­guages such as C# or Java would be also bet­ter handled us­ing ded­ic­ated tools that can make use of re­flec­tion fea­tures built in­to the lan­guage it­self in­stead of at­tempt­ing to (badly) parse the sources, plus a ded­ic­ated tool can bet­ter ad­just to spe­cif­ics of giv­en lan­guage, such as not call­ing Py­thon or Java pack­ages “namespaces”.

Fea­tures that I don’t see a point in be­cause they just ar­ti­fi­cially 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).

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.

Navbar links

The LINKS_NAVBAR1 and LINKS_NAVBAR2 op­tions define which links are shown on the top navbar, split in­to left and right column on small screen sizes. These op­tions take a list of (title, path, sub) tuples — title is the link title; path is either one of the 'pages', 'modules', 'namespaces', 'annotated', 'files' IDs or a com­pound ID; and sub is an op­tion­al sub­menu, con­tain­ing (title, path) with path be­ing in­ter­preted the same way.

By de­fault the vari­ables are defined like fol­low­ing — two items in the left column, two items in the right columns, with no sub­menus:

LINKS_NAVBAR1 = [
    ("Pages", 'pages', []),
    ("Namespaces", 'namespaces', [])
]
LINKS_NAVBAR2 = [
    ("Classes", 'annotated', []),
    ("Files", 'files', [])
]

If the title is None, it’s taken im­pli­citly from the page it links to. Empty LINKS_NAVBAR2 will cause the nav­ig­a­tion ap­pear in a single column, set­ting both empty will cause the navbar links to not be rendered at all.

A menu item is high­lighted if a com­pound with the same ID is the cur­rent page (and sim­il­arly for the spe­cial pages, … IDs).

Al­tern­at­ively, a link can be a plain HTML in­stead of the first pair of tuple val­ues, in which case it’s put in­to the navbar as-is. It’s not lim­ited to just a text, but it can con­tain an im­age, em­bed­ded SVG or any­thing else. A com­plex ex­ample in­clud­ing sub­menus fol­lows — the first navbar column will have links to namespaces Foo, Bar and Utils as a sub-items of a top-level Namespaces item and links to two sub­dir­ect­or­ies as sub-items of the Files item, with title be­ing None to have it auto­mat­ic­ally filled in by Doxy­gen. The second column has two top-level items, first link­ing to the page in­dex and hav­ing a sub­menu link­ing to an e-mail ad­dress and a fine-print page and the second link­ing to a Git­Hub pro­ject page. Note the mangled names, cor­res­pond­ing to fi­le­names of giv­en com­pounds gen­er­ated by Doxy­gen.

LINKS_NAVBAR1 = [
    (None, 'namespaces', [
        (None, 'namespaceFoo'),
        (None, 'namespaceBar'),
        (None, 'namespaceUtils'),
    ]),
    (None, 'files', [
        (None, 'dir_d3b07384d113edec49eaa6238ad5ff00'),
        (None, 'dir_cbd8f7984c654c25512e3d9241ae569f')
    ])
]
LINKS_NAVBAR2 = [
    ("Pages", 'pages', [
        ("<a href=\"mailto:mosra@centrum.cz\">Contact</a>", ),
        ("Fine print", 'fine-print')
    ]),
    ("<a href=\"https://github.com/mosra/m.css\">GitHub</a>", [])
]

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

The search bin­ary is im­pli­citly made with the tight­est pack­ing pos­sible for smal­lest down­load sizes. On large pro­jects with tens of thou­sands of sym­bols it may how­ever hap­pen that the data won’t fit and doc gen­er­a­tion fails with an ex­cep­tion such as the fol­low­ing, sug­gest­ing you to in­crease the packed type sizes:

Over­flowEr­ror: Trie res­ult ID too large to store in 16 bits, set SEARCH_RES­ULT_ID_­BYTES = 3 in your conf.py.

The rel­ev­ant con­fig­ur­a­tion is SEARCH_RESULT_ID_BYTES, SEARCH_FILE_OFFSET_BYTES and SEARCH_NAME_SIZE_BYTES. Simply up­date your conf.py with sug­ges­ted val­ues (or the Doxyfile-mcss with this op­tion pre­fixed with M_) and re­start the gen­er­at­or. Due to the way the search data get pro­cessed dur­ing seri­al­iz­a­tion it’s un­for­tu­nately not feas­ible to es­tim­ate the pack­ing sizes be­fore­hand.

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.

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
# Required to be explicitly set since Doxygen 1.9.2, otherwise the graphs
# won't be included in the output
HAVE_DOT = YES

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:

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

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

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­rid­den 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 high­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);

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.

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.

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:

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.

Nav­ig­a­tion page tem­plates

By de­fault the theme tries to match the ori­gin­al Doxy­gen list­ing pages. These pages are gen­er­ated from the index.xml file and their tem­plate name cor­res­ponds to out­put file name.

By de­fault it’s those five pages, but you can con­fig­ure any oth­er pages via the --index-pages op­tion as men­tioned in the Com­mand-line op­tions sec­tion.

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 and in ad­di­tion the FILENAME and DOXYGEN_VERSION vari­ables as above. The nav­ig­a­tion tree is provided in an index ob­ject, which has the fol­low­ing prop­er­ties:

The form of each list entry is the same:

Each list is ordered in a way that all namespaces are be­fore all classes and all dir­ect­or­ies are be­fore all files.

1.

^ a b c d e f g h i j k l m i.brief is a single-line para­graph without the en­clos­ing <p> ele­ment, rendered as HTML. Can be empty in case of func­tion over­loads.

2.

^ a b c d e f g h i.description is HTML code with the full de­scrip­tion, con­tain­ing para­graphs, notes, code blocks, im­ages etc. Can be empty in case just the brief de­scrip­tion is present.

3.

^ a b c d e f g h i j k l i.base_url, joined us­ing # with i.id form a unique URL for giv­en sym­bol. If the i.base_url is not the same as compound.url, it means giv­en sym­bol is just ref­er­enced from giv­en com­pound and its de­tailed doc­u­ment­a­tion resides else­where.

4.

^ a b c d e f i.name is just the mem­ber name, not qual­i­fied. Pre­pend compound.prefix_wbr to it to get the fully qual­i­fied name.

5.

^ a b c d e f g h i compound.has_*_details and i.has_details are True if there is de­tailed de­scrip­tion, func­tion/tem­plate/macro para­met­er doc­u­ment­a­tion, enum value list­ing or an entry-spe­cif­ic #include that makes it worth to render the full de­scrip­tion block. If False, the mem­ber should be in­cluded only in the brief list­ing on top of the page to avoid un­ne­ces­sary re­pe­ti­tion. If i.base_url is not the same as compound.url, its i.has_details is al­ways set to False.

6.

^ a b c d e f g h i.type and param.default is rendered as HTML and usu­ally con­tains links to re­lated doc­u­ment­a­tion

7.

^ a b c d e f g h i j k l m i.deprecated is set to a string con­tain­ing the de­prec­a­tion status if de­tailed docs of giv­en sym­bol con­tain the @deprecated com­mand and to None oth­er­wise. See also Ver­sion la­bels for more in­form­a­tion.

8.

^ a b c d e f g h i j k l m i.status HTML code with a la­bel or None. See Ver­sion la­bels for more in­form­a­tion.