The Configuration File

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

Format	Description
`adoc`	AsciiDoc format.
`html`	HTML format.
`xml`	XML format.

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

Command Line Options

The following options can be used to control the general behavior of MrDocs and can only be provided via the command line:

Name

Description

#define CMDLINE_OPTION(Name, Kebab, Desc)

Kebab

Desc

/* This file describes the types of Info nodes supported by MrDocs. * * It uses the same file format as LLVM .inc files generated by TableGen * with the exception that we maintain this file directly. * * The purpose of this file is to provide a list of Info nodes that can be * used by MrDocs in such a way that any code that depends on an exaustive * list of Info nodes can be generated automatically. * * The table contains the basic information for each node type, such * as the name in various casings and the description. * * How to use this table: * * 1) choose one of the following macros below, such as * INFO_PASCAL, INFO_PLURAL, INFO_UC, INFO_PASCAL_AND_UC, etc. * 2) Define this macro with the content to be rendered for each node type, * such as define INFO_PASCAL(Type) struct Type#Info; * 3) Include this file below the macro definition with * #include <mrdocs/Metadata/InfoNodes.inc> * * This will render your macro for each node type. * We do not recommend using the INFO macro directly in your code because * it might change in the future as more information about the nodes is * added. * This can make the code hard to maintain. * */

#ifndef OPTION #define OPTION(Name, Kebab, Desc) #endif

#ifndef CMDLINE_OPTION #define CMDLINE_OPTION(Name, Kebab, Desc) OPTION(Name, Kebab, Desc) #endif

#ifndef COMMON_OPTION #define COMMON_OPTION(Name, Kebab, Desc) OPTION(Name, Kebab, Desc) #endif

#if !defined(INCLUDE_OPTION_OBJECTS) && !defined(INCLUDE_OPTION_NESTED) #define INCLUDE_OPTION_NESTED #endif

CMDLINE_OPTION(inputs , inputs , Configuration or compilation database files) CMDLINE_OPTION(config , config , Configuration file: mrdocs.yml) CMDLINE_OPTION(concurrency , concurrency , The desired level of concurrency: 0 for hardware-suggested)

COMMON_OPTION (sourceRoot , source-root , Path to the root directory of the source code) COMMON_OPTION (output , output , Directory or file for generating output) COMMON_OPTION (compilationDatabase , compilation-database , Path to the compilation database or a build script to generate it)

COMMON_OPTION (cmake , cmake , CMake arguments when generating the compilation database from CMakeLists.txt) COMMON_OPTION (defines , defines , Additional defines passed to the compiler)

COMMON_OPTION (generate , generate , Documentation generator. Supported generators are: adoc/html/xml) COMMON_OPTION (addons , addons , Path to the Addons directory) COMMON_OPTION (multipage , multipage , True if output should consist of multiple files) COMMON_OPTION (baseURL , base-url , Base URL for links to source code)

COMMON_OPTION (referencedDeclarations , referenced-declarations , Extraction policy for references to external declarations) COMMON_OPTION (anonymousNamespaces , anonymous-namespaces , Extraction policy for anonymous namespace) COMMON_OPTION (inaccessibleMembers , inaccessible-members , Extraction policy for inaccessible members) COMMON_OPTION (inaccessibleBases , inaccessible-bases , Extraction policy for inaccessible bases) COMMON_OPTION (seeBelow , see-below , Namespace for symbols rendered as "see-below") COMMON_OPTION (implementationDefined , implementation-defined , Namespace for symbols rendered as "implementation-defined")

#ifndef INCLUDE_OPTION_NESTED COMMON_OPTION (input , input , Input file filters) COMMON_OPTION (filters , filters , Symbol filters) #else COMMON_OPTION (input.include , input.include , Input directories to include) COMMON_OPTION (input.filePatterns , input.file-patterns , Input file patterns) COMMON_OPTION (filters.symbols.include , filters.symbols.include , Specifies symbol inclusion patterns) COMMON_OPTION (filters.symbols.exclude , filters.symbols.exclude , Specifies symbol exclusion patterns) #endif

COMMON_OPTION (verbose , verbose , True if more information should be output to the console) COMMON_OPTION (report , report , The minimum reporting level: 0 to 4) COMMON_OPTION (ignoreMapErrors , ignore-map-errors , Continue if files are not mapped correctly) COMMON_OPTION (ignoreFailures , ignore-failures , Whether AST visitation failures should not stop the program) COMMON_OPTION (detectSfinae , detect-sfinae , Whether to detect the SFINAE idiom)

#ifdef INCLUDE_OPTION_OBJECTS #undef INCLUDE_OPTION_OBJECTS #endif

#ifdef INCLUDE_OPTION_NESTED #undef INCLUDE_OPTION_NESTED #endif

#ifdef CMDLINE_OPTION #undef CMDLINE_OPTION #endif

#ifdef COMMON_OPTION #undef COMMON_OPTION #endif

#ifdef OPTION #undef OPTION #endif

Any argument provided to MrDocs without a key is treated as one path in inputs. These can be paths to the configuration file config, the compilation-database (compilation database or build scripts), or the source-root directory. See the Common Options section for more information on these options.
The config option can be used to explicitly specify a configuration file. Any path in inputs whose filename is mrdocs.yml will also be used as the configuration file. If no configuration file is provided via inputs or config, MrDocs will attempt to find mrdocs.yml in the current directory.

The config path is interpreted relative to the current working directory by MrDocs. All other path options are interpreted relative to the mrdocs.yml configuration file.

Common Options

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

Name

Description

#define COMMON_OPTION(Name, Kebab, Desc)