Skip to content

Configuration options

Jump to bottom
Mark Gillard edited this page May 29, 2021 · 46 revisions


aliases

Doxygen @command aliases.

Schema:

A table containing alias ⇒ substitution mappings.

Example:

[aliases]
'make_link{1}' = '<a href="\1">\1</a>'
'make_link{2}' = '<a href="\1">\2</a>'

Related Doxygen options:

ALIASES



author

The author of the project.

Schema:

A string.

Example:

author = 'Mark Gillard'



autolinks

Adds additional automatic hotlinking beyond what Doxygen and tagfiles can provide alone.

Schema:

A table containing regex ⇒ uri mappings. uri can be local or a fully-qualified external link.

Example:

[autolinks]
'(?:toml::)?parse[_ ]results?' = 'classtoml_1_1parse__result.html'
'(?:toml::)?parse[_ ]errors?'  = 'classtoml_1_1parse__error.html'
'(?:toml::)?node[_ ]views?'    = 'classtoml_1_1node__view.html'



badges

Adds shields.io-style badges under your main page's banner image.

Schema:

A table containing description ⇒ [ image, uri ] mappings. image can be local or a fully-qualified external link.

Example:

[badges]
'C++20'       = [ 'badge-C++20.svg', 'https://en.cppreference.com/w/cpp/compiler_support' ]
'TOML v1.0.0' = [ 'badge-TOML.svg', 'https://toml.io/en/v1.0.0' ]



code_blocks

A table of nested options for improving how <code> blocks are rendered as HTML. See the specific entries below.



code_blocks.enums

Injects additional enum values into the syntax highligher.

Schema:

A single regex or an array of regexes.

Example:

namespace magic
{
    enum class values
    {
        a,
        b,
        c,
        COUNT
    };
}
[code_blocks]
enums = [ 'magic::values::[a-zA-Z]+' ]

ℹ️ Notes:

You do not need to add enum values from your own code or from the C++ standard library; Poxy does this for you.



code_blocks.macros

Injects additional preprocessor macro #defines into the syntax highlighter.

Schema:

A single regex or an array of regexes.

Example:

[code_blocks]
macros = [ 'TOML_[A-Z0-9_]+?', 'print_value' ]

ℹ️ Notes:

You generally do not need to add macros from your own code or C++ feature test macros since Poxy does this for you. That being said, given library-specific macros tend to be 'namespaced' using a common prefix, a catch-all regex can be a useful future-proofing mechanism.



code_blocks.namespaces

Injects additional namespaces into the syntax highlighter.

Schema:

A single regex or an array of regexes.

Example:

namespace magic
{
    namespace more_magic { /* ... */ }
}
[code_blocks]
namespaces = [ 'magic(::more_magic)?' ]

ℹ️ Notes:

You do not need to add namespaces from your own code or from the C++ standard library; Poxy does this for you.



code_blocks.numeric_literals

Injects additional numeric literal operators into the syntax highlighter.

Schema:

A single regex or an array of regexes.

Example:

constexpr uint64_t operator"" _u64 (unsigned long long n) noexcept
{
    return static_cast<uint64_t>(n);
}
[code_blocks]
numeric_literals = [ '_u64' ]



code_blocks.string_literals

Injects additional string literal operators into the syntax highlighter.

Schema:

A single regex or an array of regexes.

Example:

void operator"" _print(const char* str)
{
    std::cout << str << '\n';
}
[code_blocks]
string_literals = [ '_print' ]



code_blocks.types

Injects additional typenames into the syntax highlighter.

Schema:

A single regex or an array of regexes.

Example:

[code_blocks]
types = [ 'my::namespace::(foo|bar)' ]

ℹ️ Notes:

You do not need to add typenames from your own code or from the C++ standard library; Poxy does this for you.



cpp

Specifies the minimum C++ version your project targets. Effects:

  • Adds a badge under your main page's banner image
  • Dictates which C++ feature test macros are fed to Doxygen's preprocessor

Schema:

A string or integer containing the C++ standard year as YYYY or YY, e.g. 2003, 17, '20', etc.

Default:

The current three-yearly C++ standard as if by (current year - 2).

Example:

cpp = 17



description

A brief description of the project.

Schema:

A string.

Example:

description = 'TOML for modern C++'

ℹ️ Notes:

Poxy will attempt to derive the value from PROJECT_BRIEF in neighbouring Doxyfile or Doxyfile-mcss files if this property is not explicitly specified in poxy.toml.

Related Doxygen options:

PROJECT_BRIEF



examples

A table of nested options relating to Doxygen's discovery of example code for @include, @snippet, et cetera. See the specific entries below.



examples.paths

examples.recursive_paths

examples.patterns

Specifies the input paths and file path filter patterns used by Doxygen to discover example code specified using @include, @snippet, etc. Directories specified using recursive_paths are searched recursively, while those specified using paths are only subject to shallow searches.

Schema:

A single string or an array of strings.

Default:

  • paths and recursive_paths: No paths are specified by default.
  • patterns: * (all files are matched)

Example:

[examples]
paths           = '../examples'
recursive_paths = [ '../../include', '../../src' ]
patterns        = [ '*.h' , '*.cpp' ]

ℹ️ Notes:

Poxy will merge these paths with those specified as EXAMPLE_PATH in neighbouring Doxyfile or Doxyfile-mcss files.

Related Doxygen options:

EXAMPLE_PATH
EXAMPLE_RECURSIVE
EXAMPLE_PATTERNS



extra_files

A list of local files to copy verbatim to the output html directory.

Schema:

A single string or an array of strings.

Example:

extra_files = [
    'images/banner_small.png',
    'images/badge-awesome.svg',
    'images/badge-TOML.svg',
    'images/badge-C++20.svg'
]

Related Doxygen options:

HTML_EXTRA_FILES



favicon

Path to the icon file to use as the HTML site's favicon.

Schema:

A string.

Example:

favicon = 'images/favicon.ico'

Related m.css option:

M_FAVICON



generate_tagfile

Specifies whether a doxygen tagfile should be generated and linked to in HTML page footers.

Schema:

A boolean.

Default:

true

Example:

generate_tagfile = true

Related Doxygen options:

GENERATE_TAGFILE



github

Specifies the github repository the project relates to. Effects:

  • Adds a "GitHub" link to the navbar
  • Adds "GitHub" and "Report an issue" links to the page footer
  • Adds a "Releases" badge under the main page's banner (if private_repo is false)

Schema:

A GitHub user/repository string.

Example:

github = 'marzer/tomlplusplus'



images

A table of nested options relating to Doxygen's discovery of image files for the @image command. See the specific entries below.



images.paths

images.recursive_paths

Specifies the input paths used by Doxygen to discover images specified using the @image command. Directories specified using recursive_paths are searched recursively, while those specified using paths are only subject to shallow searches.

Schema:

A single string or an array of strings.

Example:

[images]
paths           = '../images'
# recursive_paths = [ ]

ℹ️ Notes:

Poxy will merge these paths with those specified as IMAGE_PATH in neighbouring Doxyfile or Doxyfile-mcss files.

Related Doxygen options:

IMAGE_PATH



implementation_headers

Folds documentation from internal implementation headers up into the public header they support.

Schema:

A table containing header ⇒ impl header mappings.

Example:

Given a project with the following structure:

/include
    /impl
        strings_utf8.h
        strings_utf16.h
        strings_utf32.h
    strings.h

To have all documentation parsed from the /impl/strings_XXXX.h headers appear as though it were actually from strings.h:

[implementation_headers]
'include/strings.h' = [
    'include/impl/strings_utf8.h',
    'include/impl/strings_utf16.h',
    'include/impl/strings_utf32.h'
]



inline_namespaces

Tells Doxygen which namespaces are inline namespaces, since older versions of Doxygen would lose this information.

Schema:

A single string or an array of strings.

Example:

inline_namespaces = [ 'toml::literals' ]

ℹ️ Notes:

This property is unnecessary if you're using Doxygen 1.8.19 or later.



internal_docs

Specifies that the documentation generated from this config file is 'internal'. Effects:

Schema:

A boolean.

Default:

false

Example:

internal_docs = false

Related Doxygen options:

ENABLED_SECTIONS
INTERNAL_DOCS



license

Specifies the license used by the project. Effects:

  • Adds a license link to the HTML page footer
  • Adds a badge under your main page's banner image

Schema:

An [ SDPX, uri ] pair. uri can be local or a fully-qualified external link.

Example:

license = [ 'MIT', 'https://github.com/marzer/tomlplusplus/blob/master/LICENSE' ]



logo

Specifies the project logo image to feature in the HTML navbar.

Schema:

A string.

Example:

logo = 'images/logo.png'

ℹ️ Notes:

Poxy will attempt to derive the value from PROJECT_LOGO in neighbouring Doxyfile or Doxyfile-mcss files if this property is not explicitly specified in poxy.toml.

Related Doxygen options:

PROJECT_LOGO



macros

Specifies additional macros to pass to Doxygen's preprocessor. Also makes these definitions known to the syntax highlighter.

Schema:

A table containing macro ⇒ expansion mappings.

Example:

[macros]
'TOML_ASYMMETRICAL_EQUALITY_OPS(...)' = 'static_assert(true)'
'TOML_ABI_NAMESPACE_START(...)'       = 'static_assert(true)'
'TOML_ABI_NAMESPACE_BOOL(...)'        = 'static_assert(true)'

ℹ️ Notes:

In addition to the C++ feature test macros, Poxy automatically defines many 'built-in' macros for you:

macro expansion
NDEBUG 1
DOXYGEN 1
__DOXYGEN__ 1
__doxygen__ 1
__POXY__ 1
__poxy__ 1
__has_include(...) 0
__has_attribute(...) 0
__has_cpp_attribute(...) 999999
__cplusplus the standard value per cpp

Poxy will also use any PREDEFINED values it finds in neighbouring Doxyfile or Doxyfile-mcss files.

Related Doxygen options:

PREDEFINED



meta_tags

Specifies addititional <meta> tags to add to the generated HTML <head>.

Schema:

A table of name ⇒ content mappings, where content may be a string or an integer.

Example:

[meta_tags]
'google-site-verification' = 'kjnwnkj234njk324wefknsdf'



name

The name of the project.

Schema:

A string.

Example:

name = 'toml++'

ℹ️ Notes:

Poxy will attempt to derive the value from PROJECT_NAME in neighbouring Doxyfile or Doxyfile-mcss files if this property is not explicitly specified in poxy.toml.

Related Doxygen options:

PROJECT_NAME



navbar

Specifies what appears on the navbar of each HTML page.

Schema:

A single string or list of strings:

Value Links to
annotated Same as classes
classes Project class and struct index page
files Project file hierarchy index page (per Doxygen's @file command )
github Project github repository (per config option github).
groups Index of function and type groups created using @addgroup, @ingroup, etc.
modules Same as groups
namespaces Project namespace index page
pages Index of articles created using @mainpage, @page, etc.
<a href=""></a> Custom anchor tags can be added directly.

Default:

files, groups, namespaces, classes and github (if a repository is specified).

Example

navbar = [ 'namespaces', 'classes' ]

ℹ️ Notes:

The github link is always added if a repository is specified, though you can explicitly specify it yourself if you wish to change its position on the navbar.

Related m.css options:

M_LINKS_NAVBAR1
M_LINKS_NAVBAR2



private_repo

Specifies whether the Github repository for this project is private.

Schema:

A boolean.

Default:

false

Example:

private_repo = false



robots

Specifies whether search 'bots' and webcrawlers should interact with the generated HTML.

Schema:

A boolean.

Default:

true

Example:

robots = true



show_includes

Specifies whether #include directives should be shown in HTML pages.

Schema:

A boolean.

Default:

true

Example:

show_includes = true



sources

A table of nested options relating to Doxygen's discovery and handling of source files. See the specific entries below.



sources.extract_all

Default behaviour is to only emit documentation for explicitly documented symbols to encourage careful, selective documentation practices. Override this by setting sources.extract_all to true.

Schema:

A boolean

Default:

false

Example:

[sources]
extract_all = true

Related Doxygen options:

EXTRACT_ALL

Related m.css options:

M_SHOW_UNDOCUMENTED



sources.paths

sources.recursive_paths

sources.patterns

Specifies the input paths and file path filter patterns used by Doxygen to discover documentation source files. Directories specified using recursive_paths are searched recursively, while those specified using paths are only subject to shallow searches.

Schema:

A single string or an array of strings.

Default:

  • paths and recursive_paths: No paths are specified by default.
  • patterns: *.h, *.hh, *.hxx, *.hpp, *.h++, *.inc, *.markdown, *.md, *.dox

Example:

[sources]
paths           = 'pages'
recursive_paths = [ '../include' ]
patterns        = [ '*.h' , '*.dox' ]

ℹ️ Notes:

Poxy will merge these paths with those specified as INPUT in neighbouring Doxyfile or Doxyfile-mcss files.

Related Doxygen options:

INPUT
FILE_PATTERNS
RECURSIVE



sources.strip_paths

Specifies path prefixes to strip from file paths emitted in documentation.

Schema:

A single string or an array of strings.

Example:

[sources]
strip_paths     = [ '../include' ]

ℹ️ Notes:

Poxy will merge these values with those specified as STRIP_FROM_PATH in neighbouring Doxyfile or Doxyfile-mcss files.

Related Doxygen options:

STRIP_FROM_PATH



sources.strip_includes

Specifies path prefixes to strip from #include <path/to/header.h> directives emitted in documentation.

Schema:

A single string or an array of strings.

Example:

[sources]
strip_includes  = 'include/'

ℹ️ Notes:

This property is applied after sources.strip_paths; the final rendered version of #include directives is a combination of both options.

Related Doxygen options:

STRIP_FROM_INC_PATH



tagfiles

Specifies additional tagfiles for Doxygen to use during documentation generation.

Schema:

A table of tagfile ⇒ base_uri mappings. tagfile can be local or a fully-qualified external link to a web resource (in which case it is downloaded and cached locally).

Example:

[tagfiles]
'https://marzer.github.io/tomlplusplus/tomlplusplus.tagfile.xml' = 'https://marzer.github.io/tomlplusplus/'

ℹ️ Notes:

You don't need to apply the C++ standard library tagfile from cppreference.com; Poxy automatically does this for you.

Related Doxygen options:

TAGFILES



theme

Specifies the CSS theme to use in the generated HTML pages.

Schema:

A string. May be one of the following values:

  • light
  • dark

Default:

dark

Example:

theme = 'light'

Related m.css options:

M_THEME_COLOR



warnings

A table of nested options relating to the handling of warnings. See the specific entries below.



warnings.enabled

Controls the emission of all warnings.

Schema:

A boolean.

Default:

true

Example:

[warnings]
enabled = true

ℹ️ Notes:

Poxy will attempt to derive the value from WARNINGS in neighbouring Doxyfile or Doxyfile-mcss files if this property is not explicitly specified in poxy.toml.

Related Doxygen options:

WARNINGS



warnings.treat_as_errors

Specifies whether warnings should be treated as errors and cause Poxy to exit with an error code.

Schema:

A boolean.

Default:

false

Example:

[warnings]
treat_as_errors = true

ℹ️ Notes:

Poxy will attempt to derive the value from WARN_AS_ERROR in neighbouring Doxyfile or Doxyfile-mcss files if this property is not explicitly specified in poxy.toml.

You can also enable this on the command-line using --werror. The command-line option always takes precedence over config files.

Related Doxygen options:

WARN_AS_ERROR



warnings.undocumented

Specifies if undocumented classes, types, defines etc. should cause Doxygen to emit warnings.

Schema:

A boolean.

Default:

true

Example:

[warnings]
undocumented = false

ℹ️ Notes:

Poxy will attempt to derive the value from WARN_IF_UNDOCUMENTED in neighbouring Doxyfile or Doxyfile-mcss files if this property is not explicitly specified in poxy.toml.

Related Doxygen options:

WARN_IF_UNDOCUMENTED

Clone this wiki locally