The Configuration File

MrDocs uses a configuration file to control how the documentation is generated. The file is used to specify options such as the generator to use, additional compilation options, and filters.

Here’s an example of a configuration file:

source-root: ../include
multipage: false
generate: adoc

The Usage page provides a detailed explanation of what to combine options from the configuration file and the command line. The Reference section provides a detailed explanation of the options available.

Build Options

A number of options can be used to specify with which compile options MrDocs should be run.

source-root: ..
compilation-database: ../CMakeLists.txt
cmake: '-D MRDOCS_BUILD=ON'
defines: 'MRDOCS_BUILD'

The compile options primarily come from the compilation-database file. When this file is generated from a CMakeLists.txt script, the cmake option can be used to specify additional options to pass to CMake.

Additionally, the defines option can be used to specify preprocessor definitions that should be used when generating the documentation. These definitions are included in all targets of the compilation database.

Generators

MrDocs supports multiple output formats that can be specified via the generate option:

Format Description

adoc

AsciiDoc format.

html

HTML format.

xml

XML format.

  • Asciidoc is a text-based format that is easy to read and write. It can also be converted to other formats such as HTML and Markdown.

  • HTML can be generated directly with the html format.

  • XML is a structured format that can be used in tests or as an intermediary format for other tools.

The generate option can be used to specify the output format:

# ...
generate: adoc
# ...

Generator Templates

MrDocs attempts to support various alternatives for customizing the output format and style without complex workflows to post-process XML output. For the Asciidoc and HTML generators, the desired customization can usually be achieved by modifying the templates used to generate the output.

In the root of the installation directory, you will find the share/mrdocs/addons/generator directory. This directory contains the templates used to generate the documentation with the markup formats. Users can create a copy of these files and provide their own addons directory via the addons option. This allows users to customize the output format to their needs.

addons: /path/to/custom/addons

One advantage of custom templates over post-processing XML files is the ability to access symbols as a graph. If symbol A refers to symbol B, some properties of symbol B are likely to be required in the documentation of A. All templates and generators can access a reference to B by searching the symbol tree or simply by accessing the elements A refers to.

Filters

Symbol Filters

Not all symbols in a project may be relevant to the documentation. MrDocs provides a way to filter out symbols based on their names.

filters:
  symbols: (1)
    exclude: (2)
    include: (3)
1 Optional symbols key
2 Optional exclude key
3 Optional include key

Symbol filter patterns are specified using (optionally) qualified names, and may contain wildcards:

filters:
  symbols:
    exclude:
      - 'A::B'
      - 'A::f*'

If a symbol matches a pattern in the exclude list, that symbol and its members will not be extracted:

filters:
  symbols:
    exclude:
      - 'A'
// ok, does not match any excluded pattern
void f0();

namespace A // matches the pattern 'A', will not be extracted
{
    // enclosing namespace matches an excluded pattern:
    // the symbol will not be extracted
    void f1();
}

The filters.symbols.include key can be used to override the exclude list for specific symbols. A symbol which matches an included pattern and an excluded pattern will be extracted.

This permits fine-grained control of extraction for individual members of a class or namespace:

filters:
  symbols:
    exclude:
      - 'A'
    include:
      - 'A::g*'
namespace A
{
    // enclosing namespace matches an excluded pattern, will not be extracted
    void f0();

    // ok, matches the pattern 'A::g*' which overrides the exclude list
    void g0();
}

In order for a filter pattern to match a symbol, it must consist of simple identifiers that match the name as written in its declaration: namespace aliases, typedef-names, and decltype specifiers naming the symbol cannot be used.

Specifying include patterns is only useful when the pattern would match a subset of symbols matched by an exclude pattern. An include pattern without a subsuming exclude pattern will be ignored.

File Filters

Symbols can also be filtered based on the files they are declared in. This can be useful for excluding files that exclusively contain implementation details or test code.

input:
  include:
      - ../include  (1)
  file-patterns:
      - *.hpp       (2)
1 A list of directories to include. Only symbols defined in these files will be extracted.
2 A list of file patterns to include. Only symbols defined in files matching these patterns will be extracted.

Private Symbols

The implementation-detail and see-below options can be used to designate namespaces as implementation detail namespaces.

implementation-detail: 'impl'
see-below: 'see_below'

If a namespace is designated as an implementation detail namespace, all symbols within that namespace will be marked as implementation details in the documentation.

namespace impl
{
    class A {};
}

/// @brief A foo function
A foo();

The impl namespace is designated as an implementation detail namespace, so all symbols within it will be marked as implementation details in the documentation. This means the symbol A would not be documented and the function foo could be documented as follows:

/* implementation detail */ foo();

On the other hand, if a namespace is designated as a see_below namespace, all symbols within that namespace will be marked as "see below" in the documentation.

namespace see_below
{
    class B {};
}

In the documentation, the symbol B would be marked as "see-below" and could be documented as:

class B { /* see below */ };

Reference

The following options can be defined both in the configuration file and on the command line, where the command line options always take precedence.

Command Line Options

Options that can only be provided via the command line

The following options can be used to control the general behavior of MrDocs and can only be provided via the command line. These include options to specify inputs and the configuration file, which cannot be set on the configuration file itself.

Name Description Default
inputs
(list of paths)

(Command line only) 		Configuration or compilation database files []
config
(file path)

(Required, Command line only) 		MrDocs configuration file "<cwd>/mrdocs.yml"

inputs

Configuration or compilation database files

The inputs are configuration files or compilation database files that are used to generate the documentation. These inputs can be configuration files or compilation database files. When the input ends with mrdocs.yml, it is interpreted as a configuration file, the file is read and the options are used to generate the documentation as if it was provided to the config option. When the input ends with compilation_database.json or CMakeLists.txt, it is interpreted as a compilation database file, the file is read and the compiler flags are used to generate the documentation as if it was provided to the compilation-database option.

  • Type: list of paths
  • Command line only
  • Default value: []
  • This command is a command line sink. Any command line argument that is not recognized by the parser will be passed to this command.

config

MrDocs configuration file

The configuration file is a YAML file that contains the options used to generate the documentation. The configuration file is read and the options are used to generate the documentation. The configuration file can be used to specify the source code, the output directory, the compilation database, the generator, and the filters.

  • Type: file path
  • Required
  • Command line only
  • Default value: "<cwd>/mrdocs.yml"
  • Relative paths are relative to: "&lt;cwd&gt;"

Paths

Paths to the source code and output directories

Name Description Default
source-root
(directory path) 		Path to the root directory of the source code "<config-dir>"
output
(path) 		Directory or file for generating output "<config-dir>/reference-output"
compilation-database
(file path) 		Path to the compilation database

source-root

Path to the root directory of the source code

  • Type: directory path
  • Default value: "<config-dir>"
  • Relative paths are relative to: "&lt;config-dir&gt;"

output

Directory or file for generating output

Multipage generators expect a directory. Single page generators expect a file or a directory where the file will be created. If the directory does not exist, it will be created.

  • Type: path
  • Default value: "<config-dir>/reference-output"
  • Relative paths are relative to: "&lt;config-dir&gt;"

compilation-database

Path to the compilation database

Path to the compilation database or a build script to generate it. The compilation database is a JSON file that contains the compiler commands used to build the source code. The compilation database is used to extract the compiler flags and the source files used to build the source code and extract symbols. This option also accepts the path to a build script such as CMakeLists.txt to be used to generate the compilation database. In this case, MrDocs will look for CMake in PATH or in CMAKE_ROOT and run the script to generate the compilation database file.

  • Type: file path
  • Default value:
  • Relative paths are relative to: "&lt;config-dir&gt;"

Build options

Options for building the source code

When MrDocs is responsible to running the build scripts and generating the compilation database, these options are used to build the source code.

Name Description Default
cmake
(string) 		CMake arguments when generating the compilation database from CMakeLists.txt
defines
(list of strings) 		Additional defines passed to the compiler []
use-system-stdlib
(boolean) 		Use the system standard library false
stdlib-includes
(list of paths) 		Standard Library include paths ["<mrdocs-root>/share/mrdocs/libcxx", "<mrdocs-root>/share/mrdocs/clang"]
system-includes
(list of paths) 		System include paths []
includes
(list of paths) 		Include paths []

cmake

CMake arguments when generating the compilation database from CMakeLists.txt

When the compilation-database option is a CMakeLists.txt file, these arguments are passed to the cmake command to generate the compilation_database.json.

  • Type: string
  • Default value:

defines

Additional defines passed to the compiler

Additional defines passed to the compiler when building the source code. These defines are added to the compilation database regardless of the strategy to generate it.

  • Type: list of strings
  • Default value: []

use-system-stdlib

Use the system standard library

True if the compiler has to use just the system standard library. When set to true, the compiler uses the system standard library instead of the standard library provided by the compiler.

  • Type: boolean
  • Default value: false

stdlib-includes

Standard Library include paths

Standard Library include paths. These paths are used to replace the standard library paths provided by the compiler.

  • Type: list of paths
  • Default value: ["<mrdocs-root>/share/mrdocs/libcxx", "<mrdocs-root>/share/mrdocs/clang"]
  • Relative paths are relative to: "&lt;config-dir&gt;"

system-includes

System include paths

System include paths. These paths are used to add directories to the system include search path. The system include search path is used to search for system headers. The system headers are headers that are provided by the system and are not part of the project. The system headers are used to provide the standard library headers and other system headers. The system headers are not part of the project and are not checked for warnings and errors.

  • Type: list of paths
  • Default value: []

includes

Include paths

Include paths. These paths are used to add directories to the include search path. The include search path is used to search for headers. The headers are used to provide declarations and definitions of symbols. The headers are part of the project and are checked for warnings and errors.

  • Type: list of paths
  • Default value: []

Generators

Generators to create the documentation and their options

Name Description Default
generate
(enum) 		Generator used to create the documentation "adoc"
multipage
(boolean) 		Generate a multipage documentation true
base-url
(string) 		Base URL for links to source code
addons
(path) 		Path to the Addons directory "<mrdocs-root>/share/mrdocs/addons"

generate

Generator used to create the documentation

  • Type: enum
  • Default value: "adoc"
  • Allowed values: ["adoc", "html", "xml"]

multipage

Generate a multipage documentation

Generates a multipage documentation. The output directory must be a directory. This option acts as a hint to the generator to create a multipage documentation. Whether the hint is followed or not depends on the generator.

  • Type: boolean
  • Default value: true

base-url

Base URL for links to source code

Base URL for links to source code. The base URL is used to create links to the source code in the documentation. The base URL is combined with the path to the source file to create the link.

  • Type: string
  • Default value:

addons

Path to the Addons directory

Path to the Addons directory. The Addons directory contains the template files used by generators to create the documentation. When a custom Addons directory is not specified, the default templates are used. The default templates are located at the share/mrdocs/addons directory of the MrDocs installation. Users can create custom templates by copying the default templates to a custom directory and specifying the custom directory using this option.

  • Type: path
  • Default value: "<mrdocs-root>/share/mrdocs/addons"
  • Relative paths are relative to: "&lt;config-dir&gt;"

Filters

Filters to include or exclude files and symbols from the documentation

Name Description Default
referenced-declarations
(enum) 		Extraction policy for references to external declarations "dependency"
anonymous-namespaces
(enum) 		Extraction policy for anonymous namespaces "always"
inaccessible-members
(enum) 		Extraction policy for inaccessible members "always"
inaccessible-bases
(enum) 		Extraction policy for inaccessible base classes "always"
see-below
(list of strings) 		Namespaces for symbols rendered as "see-below" []
implementation-defined
(list of strings) 		Namespaces for symbols rendered as "implementation-defined" []
input
(object) 		Include files to extract
filters
(object) 		Filters

referenced-declarations

Extraction policy for references to external declarations

Determine whether external declarations should be extracted when they are referenced in the source code. When set to always, external declarations are always extracted. When set to dependency, external declarations are extracted only if they are referenced by the source code. When set to never, external declarations are never extracted.

  • Type: enum
  • Default value: "dependency"
  • Allowed values: ["always", "dependency", "never"]

anonymous-namespaces

Extraction policy for anonymous namespaces

Determine whether symbols in anonymous namespaces should be extracted. When set to always, symbols in anonymous namespaces are always extracted. When set to dependency, symbols in anonymous namespaces are extracted only if they are referenced by the source code. When set to never, symbols in anonymous namespaces are never extracted.

  • Type: enum
  • Default value: "always"
  • Allowed values: ["always", "dependency", "never"]

inaccessible-members

Extraction policy for inaccessible members

Determine whether inaccessible members should be extracted. When set to always, inaccessible members are always extracted. When set to dependency, inaccessible members are extracted only if they are referenced by the source code. When set to never, inaccessible members are never extracted.

  • Type: enum
  • Default value: "always"
  • Allowed values: ["always", "dependency", "never"]

inaccessible-bases

Extraction policy for inaccessible base classes

Determine whether inaccessible base classes should be extracted. When set to always, inaccessible base classes are always extracted. When set to dependency, inaccessible base classes are extracted only if they are referenced by the source code. When set to never, inaccessible base classes are never extracted.

  • Type: enum
  • Default value: "always"
  • Allowed values: ["always", "dependency", "never"]

see-below

Namespaces for symbols rendered as "see-below"

Namespaces for symbols rendered as "see-below". Symbols in these namespaces are not extracted and are rendered as "see-below" in the documentation. This option is used to exclude symbols from the documentation that are considered part of the private API of the project.

  • Type: list of strings
  • Default value: []

implementation-defined

Namespaces for symbols rendered as "implementation-defined"

Namespaces for symbols rendered as "implementation-defined". Symbols in these namespaces are not extracted and are rendered as "implementation-defined" in the documentation. This option is used to exclude symbols from the documentation that are considered part of the private API of the project.

  • Type: list of strings
  • Default value: []

input

Include files to extract

Include files to extract. Only the files listed in this option are extracted. The paths are relative to the mrdocs configuration file.

  • Type: object (See below)

filters

Filters

  • Type: object (See below)

input suboptions

Name Description Default
input.include
(list of paths) 		Input directories to include []
input.file-patterns
(list of strings) 		File patterns to include []

input.include

Input directories to include

Input directories to include. Only the files in these directories are extracted. The paths are relative to the mrdocs configuration file.

  • Type: list of paths
  • Default value: []

input.file-patterns

File patterns to include

File patterns to include. Only the files that match these patterns are extracted. The patterns are relative to the input directories.

  • Type: list of strings
  • Default value: []

filters suboptions

Name Description Default
filters.symbols
(object) 		Symbol filters

filters.symbols

Symbol filters

Symbol filters. Symbols that match these filters are extracted. The filters are applied to the fully qualified name of the symbol.

  • Type: object (See below)

symbols suboptions

Name Description Default
filters.symbols.include
(list of strings) 		Specifies symbol inclusion patterns []
filters.symbols.exclude
(list of strings) 		Specifies symbol exclusion patterns []

filters.symbols.include

Specifies symbol inclusion patterns

Specifies symbol inclusion patterns. Symbols that match these patterns are extracted. The patterns are applied to the fully qualified name of the symbol.

  • Type: list of strings
  • Default value: []

filters.symbols.exclude

Specifies symbol exclusion patterns

Specifies symbol exclusion patterns. Symbols that match these patterns are not extracted. The patterns are applied to the fully qualified name of the symbol.

  • Type: list of strings
  • Default value: []

Metadata

Metadata and C++ constructs to extract

Name Description Default
detect-sfinae
(boolean) 		Detect SFINAE expressions true

detect-sfinae

Detect SFINAE expressions

When set to true, MrDocs detects SFINAE expressions in the source code and extracts them as part of the documentation. Expressions such as std::enable_if<...> are detected, removed, and documented as a requirement.

  • Type: boolean
  • Default value: true

Miscellaneous

Miscellaneous options

Name Description Default
concurrency
(unsigned integer)

(Command line only) 		Number of threads to use 0
verbose
(boolean) 		Verbose output false
report
(unsigned integer) 		The minimum reporting level: 0 to 4 1
ignore-map-errors
(boolean) 		Continue if files are not mapped correctly false
ignore-failures
(boolean) 		Whether AST visitation failures should not stop the program false

concurrency

Number of threads to use

The desired level of concurrency: 0 for hardware-suggested.

  • Type: unsigned integer
  • Command line only
  • Default value: 0
  • Minimum value: 0

verbose

Verbose output

Verbose output. When set to true, MrDocs outputs additional information during the generation of the documentation.

  • Type: boolean
  • Default value: false

report

The minimum reporting level: 0 to 4

The reporting level determines the amount of information displayed during the generation of the documentation. The levels are: 0 - no output, 1 - errors only, 2 - errors and warnings, 3 - errors, warnings, and information, 4 - errors, warnings, information, and debug information.

  • Type: unsigned integer
  • Default value: 1
  • Minimum value: 0
  • Maximum value: 4

ignore-map-errors

Continue if files are not mapped correctly

When set to true, MrDocs continues to generate the documentation even if some files are not mapped correctly. Files are not mapped correctly when the source file is not found or the compilation database does not contain the compiler flags for the source file.

  • Type: boolean
  • Default value: false

ignore-failures

Whether AST visitation failures should not stop the program

When set to true, MrDocs continues to generate the documentation even if there are AST visitation failures. AST visitation failures occur when the source code contains constructs that are not supported by MrDocs.

  • Type: boolean
  • Default value: false

Edit this Page