Inputs

To document your code, MrDocs needs to know where the source lives and how to compile it. The options on this page answer both questions. The Inputs reference lists every option with its default.

Pointing at your code

source-root is the base MrDocs uses to form the per-file paths that link each symbol page back to the source file it lives in (combined with base-url, those paths become full URLs to your repository host). It defaults to the directory holding mrdocs.yml. The example sets source-root: .. so the resulting paths are anchored at the repository root.

docs/mrdocs.yml

## Pattern: handwritten compilation database, no build system.
source-root: ..
compilation-database: compile_commands.json

compilation-database is the option that determines how MrDocs compiles your code. Basic Usage Patterns walks through complete starter projects. Pick the one closest to your project.

If MrDocs is invoking CMake on your behalf (the compilation-database value points at a CMakeLists.txt), cmake passes extra arguments through to that CMake invocation — for example '-D MY_PROJECT_TESTS=OFF' to silence test targets while configuring for the docs build.

By default, MrDocs runs the CMake build in a scratch directory and removes it afterward, automatically choosing a writable location (it honors the MRDOCS_TEMP_DIR environment variable, then the user cache and system temporary directories). Set cmake-build-dir to run the build in a fixed directory instead. That directory is reused between runs and never removed, which is useful when a CMake configure fails and you want to inspect the generated build files.

Extra includes and defines

The compilation database carries most of the flags MrDocs needs, but you can add to them. includes and system-includes add directories to the header search path, and defines adds preprocessor definitions to every entry in the database.

docs/mrdocs.yml

source-root: ..
input:
  - ../include
includes:
  - ../external
defines:
  - LIB_BUILD

include/lib/api.hpp

#ifdef LIB_BUILD
#include <extlib/types.h>

namespace lib {
/** Use an external widget from `extlib`. */
extlib::widget make_widget();
}
#endif

external/extlib/types.h

namespace extlib { struct widget {}; }

These options are usually the first to reach for when MrDocs reports that a header cannot be found.

Standard library headers

For the C and C++ standard libraries, MrDocs can use the headers installed on your system or the ones it bundles for reproducible results. use-system-stdlib and use-system-libc pick between the two; stdlib-includes and libc-includes say where the bundled headers live.

Other documentation sets

A doc comment can refer to a symbol MrDocs never extracted, e.g. a type from a dependency, or std::vector. input-tagfiles specifies tagfiles for that purpose, so the reference becomes a link to the page that documents the symbol. Each entry maps a tagfile to the base URL its documentation set is published under. Here the corpus documents area, while geom::circle belongs to a library documented elsewhere:

Example

/** Compute the area of a circle of radius `r`.

    The result is what @ref geom::circle::area reports for a
    @ref geom::circle of that radius.
*/
double area(double r);

mrdocs.yml

input-tagfiles:
  geom.tag.xml: https://geom.example/docs/

Preview

area

Compute the area of a circle of radius r.

Synopsis

Declared in <input‐tagfiles.cpp>

double
area(double r);

Description

The result is what geom::circle::area reports for a geom::circle of that radius.

A name resolves the way any other reference does, from the scope it is written in outward, so a doc comment inside namespace geom could refer to circle unqualified. Doxygen writes a tagfile for its own output with GENERATE_TAGFILE, and MrDocs with output-tagfile; cppreference.com publishes one for the standard library, which can be used to have e.g. @ref std::vector link there.