Documentation Guidelines

This section covers how to structure library documentation.

Documentation Entry Point

In the Boost release, the entry point for the documentation for a library should be in the libs/<LIBRARY NAME>/index.html directory. This means all projects should contain an index.html file in the root of the library directory.

Since the Boost releases including all source files and artifacts are available from https://www.boost.org/doc/libs/<VERSION>/, the location for published library documentation will match the following:

https://www.boost.org/doc/libs/<VERSION>/libs/<LIBRARY NAME>/index.html

For example:

https://www.boost.org/doc/libs/1_81_0/libs/json/index.html
https://www.boost.org/doc/libs/1_82_0/libs/serialization/index.html
https://www.boost.org/doc/libs/1_83_0/libs/beast/index.html

Although the content of the index.html file is up to the library author, libraries use this index.html entry point to redirect to the main documentation page located elsewhere. For instance, assuming the final library documentation is located in doc/index.html, the index.html file might contain the following:

<head>
    <meta http-equiv="refresh" content="0; URL=doc/index.html">
</head>
<body>
    Automatic redirection failed, please go to
    <a href="doc/index.html">doc/index.html</a>.
</body>
</html>

In principle, the page to which index.html redirects can be another source file in the library directory. In most cases, however, it redirects to another HTML file generated by the build system in the release process.

Required Organization

In order for a library’s documentation to be built correctly and the finished product written to the location described above, you must follow the Organization Requirements, in particular the Building Documentation section.

In particular, the source files for the documentation must be located in the doc directory of the library. Two types of documentation layouts that are supported:

Antora component documentation
Standalone documentation

Antora Component Documentation

Antora is a documentation site generator used to build the Boost website documentation and library documentation for libraries that opt to use it. A library can choose to use Antora for its documentation by including an doc/antora.yml file to the repository, such as:

name: mp11
title: Boost.Mp11
version: ~
nav:
  - modules/ROOT/nav.adoc

The navigation structure is defined in doc/modules/ROOT/nav.adoc and the documentation pages are defined in doc/modules/ROOT/pages/. All pages are written in AsciiDoc format.

Once the component is defined, it can be enabled in the Boost website repository by adding the component to the libs.playbook.yml file.

In the Boost release process, this Antora playbook is built with all the other documentation components, and the resulting HTML files are written to the doc/antora directory of the release. At this point, the Documentation Entry Point for the library documentation should be updated, so it redirects to ../../doc/antora/<LIBRARY NAME>/index.html.

For detailed instructions on how to set up an Antora component for a library, please refer to Antora Guide.

Standalone Documentation

If a library chooses not to use Antora, the doc directory of the library should contain a doc/Jamfile file that specifies how the documentation should be built. Although this build script can be used to invoke any documentation tool, common tools used for building documentation include: AsciiDoc, Doxygen, and Boost.Quickbook. When deciding to include standalone documentation with your library, the doc/Jamfile build scripts from other Boost libraries are typically used as reference for new libraries.

In the Boost release process, these scripts defined in doc/Jamfile are built for each library. The script typically builds the HTML documentation files in-place, often to doc/html/. These in-place files are then copied as-is to the release directory. For instance, if your library’s documentation is built to doc/html/index.html, the Documentation Entry Point should be updated to redirect to doc/html/index.html.

Documentation Guidelines

Documentation Entry Point

Required Organization

Antora Component Documentation

Standalone Documentation

See Also