Maintaining the Docs

Purpose of this page

We welcome improvements to the documentation! Here’s how we manage the content of the documentation files.

For information on how that content is built and published, see Building the Docs.

Future version numbers

To refer to the next release, use ‘v.x.y.z’, and make sure that there is a step to edit the file to update that text to the actual version number in the release scripts.

Creating new pages

Using the template page manually

If creating a new Markdown page, please make a copy of doc/ This contains some boilerplate text which is tedious to create by hand.

Creating one or more pages by script

If creating multiple files, on Unix, you can use the script doc/

cd doc/
./ TestingSingleObjects TestingContainers TestingCombinations

This won’t overwrite existing files. It will write out the text to paste in to other .md files, to correctly link to the new file.

For documentation files outside of doc

If the new page will be outside of the doc folder, delete the following lines at the end:


[Back to User Guide](

Linking to new pages

Two files need to be edited when new pages are added, so the new file is visible to users.

In Sphinx for Read the Docs

Each new documentation page needs to be added twice in doc/sphinx/index.rst.

  1. A line beginning :doc:, which includes the page in the Read the Docs front page.

  2. A link in a .. toctree:: section, which includes the page in the navigation panel.

Note that Sphinx detects a page’s title automatically, and will use it for the text in the hyperlink automatically, so you only need to spell out the link’s text if you want it to be different from the page’s title.

In the GitHub User Guide

Each new documentation page needs to be added to doc/

The layout here should mimic the layout generated you used in index.rst.

Adding code and file samples

We use Simon Cropp’s MarkdownSnippets tool to embed source code and other files in Markdown pages.

How it works

  • See the MarkdownSnippets documentation for how to:

    • annotate snippets of source code,

    • reference the snippets in documentation.

  • Run before commit, every time a .md file or any of the source code with snippets is updated

    • See

    • This will update the tables of contents and and any snippets in all .md files in the project.

    • If this does not work, see that script for how to install the tools it uses

Managing CMake code samples

The repository claremacrae/ApprovalTests.cpp.CMakeSamples has some sample CMake projects for using ApprovalTests.cpp in various development scenarios.

When I improve the files in that repo, I run its script claremacrae/ApprovalTests.cpp.CMakeSamples/ to convert the interesting CMake files to Markdown.

Some of those Markdown files are then embedded in the documentation for this project.

Checking the documentation

Other checks of documentation

The script can be used to do some checks of the Markdown documentation files.