Writing Documentation for Batteries C++

Writing Documentation for Batteries C++

Batteries is a work in progress, but our aim is to provide the best documentation possible for our users. This guide desecribes the tools and process we use to write, build, and deploy documentation.

Quick Start

From the Git repo root, run the shell command:

make serve-docs

Expected output:

...
INFO     -  [17:56:51] Serving on http://127.0.0.1:8000/

Now you should be able to navigate to http://localhost:8000/ and view the documentation site served by your development machine. Any changes made to the source files will be reflected automatically be reflected after running:

make mkdocs

_ NOTE: The shell commands in this document assume you have the documentation tools installed. If you want to install them on your machine natively, you can check batteries/docker/Dockerfile to see how they are installed for CI pipelines. The recommended method, however, is to run all commands inside a Docker container using the batteries/script/run-with-docker.sh script. Example:

script/run-with-docker.sh make serve-docs

What to Edit

• src/
  Doxygen-style comments in C++ source files
• config/
  Doc tool configuration and customization
  • mkdocs.yml
    Site navigation tree
  • mkdocs_overrides/
    General HTML layout customization
  • doxybook_templates/
    Generated API Reference HTML layout customization
• doc/
  Handwritten markdown files (subdirs are OK too!)
  • images/
    Static image assets
  • stylesheets/
    Handwritten CSS

Overview

The documentation site of Batteries C++ is hosted by GitHub Pages. There are many source materials that go into building the site:

• Hand-written MarkDown files (such as this one)
• Doxygen-style Doc Comments in the C++ Source Code
• Static Web Assets (e.g., images, css, etc.)
• Metadata that describes the site structure and the build process

MkDocs

At the top level, the site is statically generated using MkDocs. The MkDocs project is constructed from files gathered from various places in the Git repo, as well as automatically generated content produced by scraping the source code. The basic structure of a MkDocs project is:

• project/
  The project root directory
  • mkdocs.yml
    The MkDocs config file
  • docs/
    The site source files
    • images/
      Base directory for image files
    • stylesheets/
      Base directory for CSS style sheets
  • overrides/
    Theme partial layout overrides

The MkDocs project for Batteries is generated inside batteries/build/mkdocs/ by the Makefile target mkdocs:

make mkdocs

NOTE: The mkdocs target depends on the doxygen and doxybook2 targets, so you don't need to run those separately.

mkdocs.yml

The source file for mkdocs.yml lives at batteries/config/mkdocs.yml. This is where you configure:

• The site name ("Batteries C++")
• The theme (we currently use a customized version of Material)
• The locations of any extra .css files
• The site navigation tree (which appears on the right sidebar)
• Plugins and MarkDown language extensions

docs/

All handwritten files inside the MkDocs docs/ dir are copied from batteries/doc/. In addition, the Makefile creates a subdir called _autogen/ under docs/ containing all content generated by Doxygen and Doxybook2 (see below).

overrides/

This directory is copied from batteries/config/mkdocs_overrides/. It contains all HTML layout customizations to the Material theme. For more information, read this document.

Doxygen/Doxybook2

We scrape the C++ source code inside batteries/src/ using Doxygen to extract API documentation. The Doxygen config file lives at batteries/config/doxygen.config, and the corresponding output is produced in `batteries/build/doxygen/'.

To run just the Doxygen tool, you can run the Makefile like this:

make doxygen

NOTE: The doxygen target depends on the doxybook2 target, so you don't need to run it separately.

The default Doxygen HTML output looks much worse than what MkDocs produces, and it isn't styled according to the Material theme. To bridge the gap, we use Doxybook2. Doxybook2 takes the XML output of Doxygen and produces MarkDown files which can be formatted and styled in a manner consistent with the rest of the site.

The Doxybook2 config file lives at batteries/config/doxybook_config.json. The templates used to generate MarkDown live inside batteries/config/doxybook_templates/. You can read about how to modify these here.

Doxybook2 output is generated inside batteries/build/doxybook2/. You can regenerate this output using:

make doxybook2