////
Copyright (c) 2024 The C++ Alliance, Inc. (https://cppalliance.org)

Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Official repository: https://github.com/boostorg/website-v2-docs
////
= Documentation Guidelines
:navtitle: Guidelines

This section covers how to structure library documentation.

[[documentation-entry-point]]
== 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:

[source,asciidoc]
----
https://www.boost.org/doc/libs/<VERSION>/libs/<LIBRARY NAME>/index.html
----

For example:

[source,asciidoc]
----
https://www.boost.org/doc/libs/latest/libs/json/index.html
https://www.boost.org/doc/libs/latest/libs/serialization/index.html
https://www.boost.org/doc/libs/latest/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:

[source,html]
----
<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 xref:requirements/organization-requirements.adoc[], in particular the xref:requirements/organization-requirements.adoc#building_documentation[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

https://antora.org/[Antora,window=_blank] 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:

[source,yml]
----
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 https://github.com/boostorg/website-v2-docs[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 xref:docs/antora.adoc[].

[[standalone-documentation]]
=== 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: https://asciidoc.org/[AsciiDoc,window=_blank], https://www.doxygen.nl/[Doxygen,window=_blank], 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`.

== See Also

* xref:docs/asciidoc.adoc[]
* xref:site-docs-style-guide.adoc[]

_Revised April, 2023_

_Distributed under the Boost Software License, Version 1.0. Refer to http://www.boost.org/LICENSE_1_0.txt_.
