Skip to content

Configuration options

Jump to bottom
Mark Gillard edited this page Sep 30, 2022 · 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' ]



changelog

Adds a changelog page and a link to it in the site footer.

Schema:

A boolean or explicit string path to the changelog markdown file.

Default:

false

Example:

changelog = false # no changelog will be generated
changelog = true # find the changelog file in the poxy.toml directory or a parent
changelog = 'path/to/the/changelog.md'

ℹ️ Notes:

When setting this value to true, the library will search for the following filenames, in order:

  • CHANGELOG.md
  • CHANGELOG.txt
  • CHANGELOG
  • HISTORY.md
  • HISTORY.txt
  • HISTORY

Searching starts in the same directory as poxy.toml, and continues up through parent directories until a match is found.

Note that the file is assumed to be plain-text and will be parsed as markdown. No other formats are supported.



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++'

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' ]

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

gitlab

Specifies the GitHub or GitLab repository the project relates to. Effects:

  • Adds a repository link to the navbar
  • Adds repository and "Report an issue" links to the page footer
  • Adds a "Releases" badge under the main page's banner (if private_repo is false)
  • Linkifies issues (#999), users (@person) and pull requests (!person) in the changelog page when changelog is used

Schema:

A user/repository string.

Example:

github = 'marzer/tomlplusplus'

ℹ️ Notes:

Specify one or the other; do not specify both. If your project has a repository on both, specify only the one that is the main developer tree (i.e. not merely a mirror).



html_header

Adds an additional snippet of HTML to each page's <head> section.

Schema:

A single string.

Example:

html_header = '''
    <script> console.log("this is going to be ugly!"); </script>
    <style> div { background-color: red; } </style>
''''

ℹ️ Notes:

This option is exposed for more advanced scenarios since most things you'd typically put in a page's <head> already have their own configuration options:

Related m.css options:

HTML_HEADER



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 = [ ]

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



jquery

Specifies whether jQuery should be included as part of the generated HTML.

Schema:

A boolean

Default:

false

Example:

jquery = true

ℹ️ Notes:

Poxy itself does not (currently) make use of jQuery; this is provided as a convenience if you wish to make use of it in additional script files added via scripts. Setting this to true if you do not intend to add any of your own custom javascript serves no purpose.



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'

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_builtin(...) 0
__has_feature(...) 0
__has_include(...) 0
__has_attribute(...) 0
__has_cpp_attribute(...) 999999
__cplusplus the standard value per cpp

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++'

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



scripts

A list of javascript files to include as <script> tags in the <head> of each generated HTML page.

Schema:

A single string or an array of strings.

Example:

scripts = [
    'some_local_script.js',
    'https://code.jquery.com/jquery-3.6.0.min.js'
]

ℹ️ Notes:

Any local files will be copied to the output directory as if by adding them to extra_files.

Related Doxygen options:

HTML_EXTRA_FILES



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' ]

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' ]

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



stylesheets

A list of CSS files to include as <link> tags in the <head> of each generated HTML page.

Schema:

A single string or an array of strings.

Example:

stylesheets = [
    'my_fancy_styles.css',
    'https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600'
]

ℹ️ Notes:

Any local files will be copied to the output directory as if by adding them to extra_files.

Related Doxygen options:

HTML_EXTRA_STYLESHEET



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 default visual 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'

ℹ️ Notes:

As of v0.7.0 this option only controls the default theme to use, with there being a navbar button for users to switch between light and dark as they please.

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

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:

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

Related Doxygen options:

WARN_IF_UNDOCUMENTED

Clone this wiki locally