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/TemplatePage.md. 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/create_page.sh

cd doc/
./create_page.sh 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](https://github.com/approvals/ApprovalTests.cpp/blob/master/doc/README.md#top)

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.

A line beginning :doc:, which includes the page in the Read the Docs front page.
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/README.md.

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

Internal links need to be absolute

All references to other files in this project, such as hyperlinks and images, must specify the full path from the root of the repository. This is needed for links to work correctly on the Read the Docs.

For example, use this:

* [this link will work everywhere](/doc/Reporters.md#top)

Not this:

* [this link is wrong](doc/Reporters.md#top)

And not this:

* [this link is wrong](Reporters.md#top)

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 run_markdown_templates.sh before commit, every time a .md file or any of the source code with snippets is updated
- See run_markdown_templates.sh.
- 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/create_markdown.py to convert the interesting CMake files to Markdown.

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

See CMakeIntegration.md for the final result.

Checking the documentation

Automated checking of links in documentation

There is a “markdown-link-check” github workflow that checks for broken links all in the Markdown files. It checks for missing file names, but will not detect missing anchors.

It runs the script scripts/check_links.sh …
… which uses the configuration file mlc_config.json …
… and runs tcort’s markdown-link-check

If there are any failures, the output is slightly verbose to look through - you have to find lines beginning [*], but I think that these will be sufficiently few and far between that this is good enough.