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.

More information about the generators can be found in the Generators page.

YAML Schema

To get linting and autocompletion in the config file, a schema for the config can be specified. In JetBrains IDEs, # $schema: <url> can be used to bind a schema to a file. In editors with plugins based on the YAML language server, # yaml-language-server: $schema=<url> can be used. The schema for mrdocs.yml is provided here. The following shows an example of a file specifying an inline-schema that’s compatible with JetBrains IDEs and editors using the YAML language server.

# $schema: https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json
# yaml-language-server: $schema=https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json

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

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.

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
cmd-line-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"

cmd-line-inputs

Configuration or compilation database files

The inputs are configuration files or compilation database files that used to generate the documentation. 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"

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

Path to the root directory of the source code. This path is used as a default for input files and a base for relative paths formed from absolute paths.

  • Type: directory path
  • Default value: "<config-dir>"

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"

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:

Filters

Filters to include or exclude files and symbols from the documentation

Name Description Default
input
(list of paths) 		Input directories to extract symbols from ["<source-root>/."]
recursive
(boolean) 		Recursively include files from "input" paths true
file-patterns
(list of path-globs) 		File patterns to include ["*.hpp", "*.h", "*.hh", "*.ipp", "*.inc", "*.cpp", "*.cc", "*.cxx", "*.c", "*.hxx"]
exclude
(list of paths) 		Input directories to exclude []
exclude-patterns
(list of path-globs) 		File patterns to exclude []
include-symbols
(list of symbol-globs) 		Symbol patterns to include []
exclude-symbols
(list of symbol-globs) 		Symbol patterns to exclude []
see-below
(list of symbol-globs) 		Symbols rendered as "see-below" []
implementation-defined
(list of symbol-globs) 		Symbols rendered as "implementation-defined" []

input

Input directories to extract symbols from

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

  • Type: list of paths
  • Default value: ["<source-root>/."]

Example

include/libavcodec/avcodec.h
/** Allocate a new packet on the heap. */
int av_packet_alloc(void);

/** Release a packet allocated with `av_packet_alloc`. */
void av_packet_free(void);
include/libavformat/avformat.h
// Filtered out: `input: include/libavcodec` scopes extraction to that
// directory, so the format-library functions never enter the corpus.
// The directory matters because both libraries put their declarations
// at global scope under the same `av_*` prefix, so a name-based filter
// could not distinguish them.
int av_open_input_file(void);
void av_close_input_file(void);
input.cpp
#include <libavcodec/avcodec.h>
#include <libavformat/avformat.h>
mrdocs.yml
input:
  - include/libavcodec
Preview·input

av_packet_alloc

Allocate a new packet on the heap.

Synopsis

Declared in <libavcodec/avcodec.h>

int
av_packet_alloc();

av_packet_free

Release a packet allocated with av_packet_alloc.

Synopsis

Declared in <libavcodec/avcodec.h>

void
av_packet_free();

recursive

Recursively include files from "input" paths

Recursively include files. When set to true, MrDocs includes files in subdirectories of the input directories. When set to false, MrDocs includes only the files in the input directories.

  • Type: boolean
  • Default value: true

Example

include/cli/detail/tokens.hpp
namespace cli::detail {
// Filtered out: lives in a subdirectory that `recursive: false`
// skips, so `cli::detail::tokenize` never enters the corpus.
void tokenize(char const* arg);
}
include/cli/parse.hpp
namespace cli {
/** Parses command-line arguments into an option set. */
void parse(int argc, char** argv);
}
recursive.cpp
#include <cli/parse.hpp>
#include <cli/detail/tokens.hpp>
mrdocs.yml
input:
  - include/cli
recursive: false
Preview·recursive

cli::parse

Parses command‐line arguments into an option set.

Synopsis

Declared in <cli/parse.hpp>

void
parse(
    int argc,
    char** argv);

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 path-globs
  • Default value: ["*.hpp", "*.h", "*.hh", "*.ipp", "*.inc", "*.cpp", "*.cc", "*.cxx", "*.c", "*.hxx"]

exclude

Input directories to exclude

Symbols defined in files in these directories are not extracted even if they are in the list of include directories. When relative, the paths are relative to the directory of the mrdocs configuration file. For instance, "include/experimental" will exclude all files in the directory <config-dir>/include/experimental.

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

Example

include/httpd/server.hpp
namespace httpd {

/** Start the HTTP server on `port`. */
void start(int port);

/** Stop the running server. */
void stop();

}
include/zlib/zlib.h

// Vendored copy of zlib's public API. Documented upstream at
// https://zlib.net/, not here. `exclude: include/zlib` keeps the
// vendored library out of the rendered docs so it does not appear
// alongside the httpd API.

/* Compress `src` into `dst` using DEFLATE. */
int compress2(unsigned char* dst, unsigned long* dstLen,
              unsigned char const* src, unsigned long srcLen,
              int level);

/* Decompress a DEFLATE-compressed buffer. */
int uncompress(unsigned char* dst, unsigned long* dstLen,
               unsigned char const* src, unsigned long srcLen);
exclude.cpp
#include <httpd/server.hpp>
#include <zlib/zlib.h>
mrdocs.yml
exclude:
  - include/zlib
Preview·exclude

httpd::start

Start the HTTP server on port.

Synopsis

Declared in <httpd/server.hpp>

void
start(int port);

httpd::stop

Stop the running server.

Synopsis

Declared in <httpd/server.hpp>

void
stop();

exclude-patterns

File patterns to exclude

File patterns to exclude. Files that match these patterns are not extracted even if they are in the list of include directories. The patterns are relative to the configuration file. A single * will match all files in the directory. Double ** will match all files in the directory and its subdirectories.

  • Type: list of path-globs
  • Default value: []

Example

include/payments/_generated/messages.hpp
namespace payments::gen {
struct AuthorizeRequest {};
struct AuthorizeResponse {};
}
include/payments/payments.hpp
namespace payments {

/** Authorize a payment of `amount` against `account`. */
bool authorize(char const* account, double amount);

}
include/storage/_generated/messages.hpp

// Generated by the build (protoc, gRPC, OpenAPI, …); do not edit by
// hand. Every component in this project keeps its generated headers
// next to the hand-written ones under a `_generated/` subdirectory,
// so `exclude-patterns: '**/_generated/**'` drops them all at once.

namespace storage::gen {
struct PutRequest {};
struct PutResponse {};
}
include/storage/storage.hpp
namespace storage {

/** Persist a value under `key`. */
void put(char const* key, char const* value);

}
exclude-patterns.cpp
#include <storage/storage.hpp>
#include <storage/_generated/messages.hpp>
#include <payments/payments.hpp>
#include <payments/_generated/messages.hpp>
mrdocs.yml
exclude-patterns:
  - '**/_generated/**'
Preview·exclude-patterns

payments::authorize

Authorize a payment of amount against account.

Synopsis

Declared in <payments/payments.hpp>

bool
authorize(
    char const* account,
    double amount);

storage::put

Persist a value under key.

Synopsis

Declared in <storage/storage.hpp>

void
put(
    char const* key,
    char const* value);

include-symbols

Symbol patterns to include

If any patterns are defined here, only symbols that match one of these patterns are extracted. The patterns are applied to the fully qualified name of the symbol without any leading "::". A single "*" will match all symbols in the namespace. Double "**" will match all symbols in the namespace and its subnamespaces. The patterns also support "?" for any chars, "[<chars>]" for charsets, "[^<chars>]" for inverted charsets, and "{<glob>,...}" for alternatives.

  • Type: list of symbol-globs
  • Default value: []

Example

Input
namespace lib {
namespace detail {
/// An internal helper that should not appear in the docs.
int helper();
}

/// The library's only public entry point.
int run();
}
mrdocs.yml
include-symbols:
  - 'lib::run'
Preview·include-symbols

lib::run

The library's only public entry point.

Synopsis

Declared in <include‐symbols.cpp>

int
run();

exclude-symbols

Symbol patterns to exclude

A symbol that matches one of these patterns is not extracted even if whitelisted by "include-symbols". See the documentation for "include-symbols" for the pattern syntax.

  • Type: list of symbol-globs
  • Default value: []

Example

include/jzon/extra/utilities.hpp
namespace jzon::extra {

// Filtered out: `exclude-symbols: 'jzon::extra::**'` drops these
// symbols by qualified name, so the `jzon::extra` namespace and its
// members never enter the rendered docs.
void enable_trace();
void disable_trace();

}
include/jzon/parser.hpp
namespace jzon {

/** Validate that the document is well-formed JSON.

    Parses `source` without constructing a value tree, reporting only
    whether the input conforms to RFC 8259. Comments and trailing
    commas are rejected.

    @param source A null-terminated UTF-8 JSON document.
    @return `true` if the document is syntactically valid JSON, `false`
            if any syntactic error is encountered.
*/
bool validate(char const* source);

}
exclude-symbols.cpp
#include <jzon/parser.hpp>
#include <jzon/extra/utilities.hpp>
mrdocs.yml
exclude-symbols:
  - 'jzon::extra::**'
Preview·exclude-symbols

jzon::validate

Validate that the document is well‐formed JSON.

Synopsis

Declared in <jzon/parser.hpp>

bool
validate(char const* source);
Description

Parses source without constructing a value tree, reporting only whether the input conforms to RFC 8259. Comments and trailing commas are rejected.

Return Value

true if the document is syntactically valid JSON, false if any syntactic error is encountered.

Parameters

Name

Description

source

A null‐terminated UTF‐8 JSON document.

see-below

Symbols rendered as "see-below"

Symbols that match one of these filters are tagged as "see-below" in the documentation, and so do symbols in scopes tagged as "see-below". This option is used to remove details about symbols that are considered part of the private API of the project. In the documentation page for this symbol, the synopsis of the implementation is rendered as "see-below" and members of scopes (such as a namespace or record) are not listed. The rest of the documentation is rendered as usual. See the documentation for "include-symbol" for the pattern syntax.

  • Type: list of symbol-globs
  • Default value: []

Example

include/netz/buffer_view.hpp
namespace netz {

/** A non-owning view of a contiguous byte range.

    Used as the parameter and return type for the framing helpers in
    `netz::stream` and as the buffer surface presented to async read
    handlers. Stores a pointer and a length, and does not extend the
    lifetime of the storage it refers to.
*/
class buffer_view
{
public:
    unsigned char const* data() const noexcept;
    unsigned long size() const noexcept;
};

}
include/netz/stream.hpp
namespace netz {

/** Locate the first complete packet at the start of the buffer.

    Scans `input` for a frame boundary. The returned view aliases the
    same memory as `input`, so the storage behind `input` must outlive
    the returned view.

    @param input Bytes received from the stream, up to the caller's
                 current fill mark.
    @return A view of the bytes belonging to the first packet, or an
            empty view if no complete packet is present yet.
*/
buffer_view first_packet(buffer_view input);

}
see-below.cpp
#include <netz/stream.hpp>
mrdocs.yml
see-below:
  - 'netz::buffer_view'
Preview·see-below

netz::buffer_view

A non‐owning view of a contiguous byte range.

Synopsis

Declared in <netz/buffer_view.hpp>

class buffer_view { /* see-below */ };
Description

Used as the parameter and return type for the framing helpers in netz::stream and as the buffer surface presented to async read handlers. Stores a pointer and a length, and does not extend the lifetime of the storage it refers to.

netz::first_packet

Locate the first complete packet at the start of the buffer.

Synopsis

Declared in <netz/stream.hpp>

buffer_view
first_packet(buffer_view input);
Description

Scans input for a frame boundary. The returned view aliases the same memory as input, so the storage behind input must outlive the returned view.

Return Value

A view of the bytes belonging to the first packet, or an empty view if no complete packet is present yet.

Parameters

Name

Description

input

Bytes received from the stream, up to the caller's current fill mark.

implementation-defined

Symbols rendered as "implementation-defined"

Symbols that match one of these filters are tagged as "implementation-defined" in the documentation, and so do symbols in scopes tagged as "implementation-defined". This option is used to exclude symbols from the documentation that are considered part of the private API of the project. An "implementation-defined" symbol has no documentation page in the output. If any other symbol refers to it, the reference is rendered as "implementation-defined". See the documentation for "include-symbol" for the pattern syntax.

  • Type: list of symbol-globs
  • Default value: []

Example

include/logr/detail/scope_token.hpp
namespace logr::detail {
struct scope_token { ~scope_token(); };
}
include/logr/log.hpp
namespace logr {

/** Attach a key/value pair to every log line in the current scope.

    The context stays attached until the returned token is destroyed.
    Hold it in `auto`; nested contexts stack and unwind in reverse order.

    @par Example
    @code
    void handle_request(request const& req) {
        auto ctx = logr::scoped_context("request_id", req.id);
        do_work(req);
    }
    @endcode

    @param key   The context name surfaced on each log line.
    @param value The context value surfaced on each log line.
    @return An opaque RAII token whose lifetime governs how long the pair
            stays attached. The type is implementation-defined; store it
            in `auto`.
*/
detail::scope_token scoped_context(char const* key, char const* value);

}
implementation-defined.cpp
#include <logr/log.hpp>
mrdocs.yml
implementation-defined:
  - 'logr::detail::**'
Preview·implementation-defined

logr::scoped_context

Attach a key/value pair to every log line in the current scope.

Synopsis

Declared in <logr/log.hpp>

/* implementation-defined */
scoped_context(
    char const* key,
    char const* value);
Description

The context stays attached until the returned token is destroyed. Hold it in auto; nested contexts stack and unwind in reverse order.

Example
void handle_request(request const& req) {
    auto ctx = logr::scoped_context("request_id", req.id);
    do_work(req);
}
Return Value

An opaque RAII token whose lifetime governs how long the pair stays attached. The type is implementation‐defined; store it in auto.

Parameters

Name

Description

key

The context name surfaced on each log line.

value

The context value surfaced on each log line.

Metadata Extraction

Metadata and C++ semantic constructs to extract

MrDocs extracts metadata and C++ semantic constructs from the source code to create the documentation. Semantic constructs are patterns not directly represented in the source code AST but can be inferred from the corpus, such as SFINAE. The following options control the extraction of metadata and C++ semantic constructs.

Name Description Default
sfinae
(boolean) 		Detect and reduce SFINAE expressions true
private-members
(boolean) 		Extraction policy for private class members false
private-bases
(boolean) 		Extraction policy for private base classes true
anonymous-namespaces
(boolean) 		Extraction policy for anonymous namespaces true

sfinae

Detect and reduce 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

Example

Input
#include <type_traits>

/** Multiply by two, but only for integers.

    The `std::enable_if_t` SFINAE on the return type
    restricts the overload to integral arguments.
*/
template <class T>
std::enable_if_t<std::is_integral_v<T>, T>
twice(T x);
mrdocs.yml
sfinae: true
Preview·sfinae

twice

Multiply by two, but only for integers.

Synopsis

Declared in <sfinae.cpp>

template<class T>
T
twice(T x)
requires std::is_integral_v<T>;
Description

The std::enable_if_t SFINAE on the return type restricts the overload to integral arguments.

private-members

Extraction policy for private class members

Determine whether private class members should be extracted

  • Type: boolean
  • Default value: false

private-bases

Extraction policy for private base classes

Determine whether private base classes should be extracted

  • Type: boolean
  • Default value: true

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: boolean
  • Default value: true

Generators

Generators to create the documentation and their options

Name Description Default
generator
(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"
tagfile
(file path) 		Path for the tagfile "<output>/reference.tag.xml"
legible-names
(boolean) 		Use legible names true
embedded
(boolean) 		Output an embeddable document false

generator

Generator used to create the documentation

The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The generator can create different types of documentation such as HTML, XML, and AsciiDoc.

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

Example

Input
/// Multiply two integers.
int multiply(int a, int b);
mrdocs.yml
generator: adoc
Preview·generator

multiply

Multiply two integers.

Synopsis

Declared in <generator.cpp>

int
multiply(
    int a,
    int b);

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

Example

mrdocs.yml
multipage: 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:

Example

Input
/** Compute the area of a circle of radius `r`. */
double area(double r);
mrdocs.yml
base-url: https://github.com/example/geom/blob/main/
Preview·base-url

area

Compute the area of a circle of radius r.

Synopsis

Declared in <base‐url.cpp>

double
area(double r);

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"

tagfile

Path for the tagfile

Specifies the full path (filename) where the generated tagfile should be saved. If left empty, no tagfile will be generated.

  • Type: file path
  • Default value: "<output>/reference.tag.xml"

legible-names

Use legible names

Use legible names for ids in the documentation. When set to true, MrDocs uses legible names for symbols in the documentation. These are symbols that are legible but still safe for URLs. When the option is set to false, MrDocs uses a hash of the symbol ID.

  • Type: boolean
  • Default value: true

Example

mrdocs.yml
multipage: true
legible-names: true

embedded

Output an embeddable document

Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. This option is useful for producing documents that can be inserted into an external template.

  • Type: boolean
  • Default value: false

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 C++ standard library false
stdlib-includes
(list of paths) 		C++ Standard Library include paths ["<mrdocs-root>/share/mrdocs/headers/libcxx", "<mrdocs-root>/share/mrdocs/headers/clang"]
use-system-libc
(boolean) 		Use the system C standard library false
libc-includes
(list of paths) 		Standard Library include paths ["<mrdocs-root>/share/mrdocs/headers/libc-stubs"]
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 C++ standard library

To achieve reproducible results, MrDocs bundles the LibC++ headers. To use the C++ standard library available in the system instead, set this option to true.

  • Type: boolean
  • Default value: false

stdlib-includes

C++ Standard Library include paths

When use-system-stdlib is disabled, the C++ standard library headers are available in these paths.

  • Type: list of paths
  • Default value: ["<mrdocs-root>/share/mrdocs/headers/libcxx", "<mrdocs-root>/share/mrdocs/headers/clang"]

use-system-libc

Use the system C standard library

To achieve reproducible results, MrDocs bundles the LibC headers with its definitions. To use the C standard library available in the system instead, set this option to true.

  • Type: boolean
  • Default value: false

libc-includes

Standard Library include paths

When use-system-libc is disabled, the C standard library headers are available in these paths.

  • Type: list of paths
  • Default value: ["<mrdocs-root>/share/mrdocs/headers/libc-stubs"]

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

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