Usage

MrDocs invocation

For consistency, these instructions assume you have the following environment variables set:

MRDOCS_ROOT=/path/to/mrdocs
PROJECT_SOURCE_DIR=/path/to/your/project/source
MRDOCS_CONFIG=$PROJECT_SOURCE_DIR/docs/mrdocs.yml
PROJECT_BUILD_DIR=$PROJECT_SOURCE_DIR/build-docs

Where MRDOCS_ROOT is the path of the mrdocs executable, and MRDOCS_CONFIG is the path to the mrdocs.yml configuration file. We also assume PROJECT_SOURCE_DIR is the path to the root of your project’s source code, where its main CMakeLists.txt file is located, and PROJECT_BUILD_DIR is the path to the directory where you want to generate the documentation. Feel free to change these variables to suit your needs.

The first step to generate your documentation is to generate the compile_commands.json file by running cmake with the -DCMAKE_EXPORT_COMPILE_COMMANDS=ON flag.

cd $PROJECT_SOURCE_DIR
mkdir $PROJECT_BUILD_DIR
cd $PROJECT_BUILD_DIR
cmake .. -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

At this step, you can also add any other flags you want to pass to cmake, such as -DCMAKE_BUILD_TYPE=Release or -DCMAKE_CXX_COMPILER=clang++. By running CMake with the CMAKE_EXPORT_COMPILE_COMMANDS flag, you will generate a compile_commands.json file in your build directory. This file contains all the information mrdocs needs to generate the documentation.

Now let’s generate the reference files. The following command will generate the documentation with the most common options:

cd $PROJECT_BUILD_DIR
MRDOCS_OUTPUT=$PROJECT_BUILD_DIR/docs/reference/adoc
$MRDOCS_ROOT/mrdocs $PROJECT_BUILD_DIR/compile_commands.json --config=$MRDOCS_CONFIG --addons=$MRDOCS_ROOT/addons --output=$MRDOCS_OUTPUT

Here’s a description of these options:

  • --config=$MRDOCS_CONFIG: the path to the mrdocs.yml configuration file. This file configures which generator is used, which directory to process, and what symbols should be extracted.

  • --addons=$MRDOCS_ROOT/addons: the path to the addons directory. This directory contains the addons that are used to generate the documentation. Among other things, it contains the default templates for the generator. This option defaults to current directory if not provided.

  • --output=$MRDOCS_ROOT/output/adoc: the path to the output directory. This is where the generated documentation will be placed.

MrDocs ignores non-c++ source files, so nothing more needs to be done to generate the documentation for your project.

Demos

A few examples of reference documentation generated with MrDocs are available in https://mrdocs.com/demos/.

MrDocs configuration file

The mrdocs.yml configuration file contains information about the project that is not available in the compile_commands.json file or from the command line. The most important information is the source-root options, which determines the root of the source tree relative to the mrdocs.yml file.

Other options are available, such as the concurrency option, which determines the number of threads mrdocs will use to generate the documentation. This option defaults to the number of cores available on the machine.

concurrency: 1      # number of threads to use
source-root: ../    # source files relative to the mrdocs.yml file
multipage: false    # generate multiple pages
verbose: true       # print verbose output

MrDocs CMake Module

MrDocs also provides a CMake module that can be used to generate the documentation from your project’s script. You can include the CMake module with:

find_package(MrDocs REQUIRED)
# ...
include(MrDocs)

The module will define the add_mrdocs function, which can be used define a CMake target that generates the documentation for your project. The syntax is similar to other cmake functions, such as add_executable or add_library:

set(CMAKE_CXX_STANDARD_INCLUDE_DIRECTORIES ${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES})
add_mrdocs(<name>
    [EXCLUDE_FROM_ALL]
    [CONFIG <mrdocs.yml>]
    [ADDONS <addons-dir>]
    [COMMENT comment]
    [OUTPUT <output-dir>]
    [<source>...])

The function adds a custom target called <name> which builds the documentation the source files listed in the command invocation. The <name> corresponds to the logical target name and must be globally unique within a project.

  • If EXCLUDE_FROM_ALL is given the corresponding property will be set on the created target. See documentation of the EXCLUDE_FROM_ALL target property for details.

  • The CONFIG option specifies the path to the mrdocs.yml configuration file. If not specified, the function will look for the configuration file in your project directory.

  • The ADDONS option specifies a custom path to the addons directory. By default, the function will use the addons directory in the MrDocs installation directory.

  • The OUTPUT option specifies the path to the output directory. If not specified, the function will use the default output directory, which is relative to the current binary directory. The complete default path is constructed based on the current binary directory and the options passed to the command (such as docs/adoc).

  • The COMMENT option specifies a comment that will be displayed when the target is built. If not specified, the comment will be generated automatically according to the input options.

The <source> arguments specify files on which the generated documentation depends. The custom target will depend on these source files. This means if these files are created with other add_custom_command() command calls in the same directory, they will be brought up to date when the target is built.