mirror of
https://github.com/boostorg/website-v2-docs.git
synced 2026-01-19 04:42:17 +00:00
108 lines
5.0 KiB
Plaintext
108 lines
5.0 KiB
Plaintext
////
|
|
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/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:
|
|
|
|
[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_.
|