docs(contributor-guide): update Antora guide

README.adoc

@@ -13,62 +13,147 @@ Official repository: https://github.com/boostorg/website-v2-docs
 
 == Antora
 
-This tool renders the documentation for Boost modules whose documentation use asciidoc.
+ https://antora.org/[Antora] is a static site generator designed for creating documentation sites from AsciiDoc content.
+The tool renders the documentation for Boost modules whose documentation are defined as components in the Antora playbook.
 
 == Installing Antora
 
-CAUTION: The workflow may change in the future.
-
 === Dependencies
 
-Antora requires Node.js:
+Antora requires https://nodejs.org[Node.js,window=_blank]:
 
 [source,bash]
 ----
 $ node -v
 ----
 
-This command should return an active Node.js LTS version number:
+This command should return the Node.js version number:
 
 [source,console]
 ----
 v16.18.0
 ----
 
-If you have Node.js installed, but it isn’t an active LTS version, you need to upgrade Node.js.
+Antora requires Node.js version 16 or later.
+If you have Node.js installed but need to upgrade it:
 
 [source,bash]
 ----
 $ nvm install --lts
 ----
 
-=== Install Antora
+The following instructions also require https://git-scm.com/[Git,window=_blank] to clone the repository:
 
-After cloning the project, you need to https://docs.antora.org/antora/latest/install/install-antora/[install] Antora command line interface (CLI) and the Antora site generator describe in the `package.json` file:
+[source,bash]
+----
+$ git --version
+----
+
+This command should return the Git version number:
+
+[source,console]
+----
+git version 2.25.1
+----
+
+=== Cloning the repository
+
+To clone the repository that defines the Antora playbook for the Boost documentation:
+
+[source,bash]
+----
+$ git clone https://www.github.com/boostorg/website-v2-docs
+----
+
+This command clones the repository into a directory named `website-v2-docs`.
+This directory contains the Antora playbook files `site.playbook.yml` (website documentation) and `libs.playbook.yml` (library documentation).
+
+[[running-antora]]
+=== Running Antora
+
+After cloning the project, you need to install its dependencies using the Node.js package manager, npm:
 
 [source,bash]
 ----
 $ npm ci
 ----
 
-Verify the antora command is now available by running:
+Then build the Antora UI bundle used for the documentation:
 
 [source,bash]
 ----
-$ npx antora -v
+$ cd antora-ui
+$ npx gulp
+$ cd ..
+----
+
+The `npx` command, which comes with npm, can be used to build any of the playbooks in the repository.
+
+[source,bash]
+----
+$ npx antora --fetch libs.playbook.yml
+----
+
+Or to build the website documentation:
+
+[source,bash]
+----
+$ npx antora --fetch site.playbook.yml
+----
+
+This commands will build the documentation in the `build/` directory.
+
+`npx` will download the Antora CLI and the Antora site generator, and then run the `antora` command with the specified playbook.
+These dependencies are cached locally, so the next time you run `npx antora`, it will be faster.
+
+In the release process, Antora is called with extra attributes used by the documentation components.
+For instance:
+
+[source,bash]
+----
+$ npx antora --fetch --attribute page-boost-branch=master --attribute page-boost-ui-branch=master --attribute page-commit-id=151c2ac libs.playbook.yml
+----
+
+[IMPORTANT]
+====
+Instead of using the Antora versioning control system, we render the documentation for a single version by setting `version: ~` in the `antora.yml` file.
+The `--attribute` options let us render the playbook for a single documentation version with context about the current version.
+====
+
+The `libdoc.sh` script simplifies the process by building the UI bundle, identifying these attributes, and running the Antora command with the specified playbook.
+
+[source,bash]
+----
+$ ./libdoc.sh master
+----
+
+Or to build the website documentation:
+
+[source,bash]
+----
+$ ./sitedoc.sh master
 ----
 
 [source,console]
 ----
-@antora/cli: 3.1.2
+Site generation complete!
-@antora/site-generator: 3.1.2
+Open file:///home/user/path/to/antora/build/master/doc in a browser to view your site.
+Site generation complete!
+Open file:///home/user/path/to/antora/build/doc in a browser to view your site.
 ----
 
-You also have the option of installing Antora globally so that the antora command is available on your `PATH`.
+The `build.sh` script identifies the branch of the current repository and runs the `sitedoc.sh` script with the branch name as an argument:
 
 [source,bash]
 ----
-$ npm i -g @antora/cli@3.1 @antora/site-generator@3.1
+$ ./build.sh
+----
+
+Although not necessary, you also have the option of installing Antora globally so that the antora command is available on your `PATH`.
+
+[source,bash]
+----
+$ npm i -g @antora/cli @antora/site-generator
 ----
 
 [source,bash]
@@ -76,90 +161,27 @@ $ npm i -g @antora/cli@3.1 @antora/site-generator@3.1
 $ antora -v
 ----
 
-[source,console]
+Read more about antora on their https://docs.antora.org/antora/latest/install-and-run-quickstart/[Quickstart guide,window=_blank].
-----
-@antora/cli: 3.1.2
-@antora/site-generator: 3.1.2
-----
 
-Read more about antora on their https://docs.antora.org/antora/latest/install-and-run-quickstart/[Quickstart guide]
+== Playbook Components
-
-== Generating the website
 
 The website is composed of components defined in the `content.sources` field of its playbook file
 `site.playbook.yml`.
-To generate the `develop` version of the website, run the Antora command with the following options:
+All components of the website are relative to the website-v2-docs repository.
-
-[source,bash]
-----
-npx antora --fetch --attribute boost_version=develop --attribute boost_site_prefix=develop/ site.playbook.yml
-----
-
-This should build the website in `build/develop/doc/`.
-
-[IMPORTANT]
-====
-Notice the `--attribute` options.
-Instead of using the Antora versioning control system, we render the documentation for a single version.
-To achieve this, we use an Antora extension that let us render the playbook for a single documentation version via these attributes.
-By setting `--attribute boost_version=develop`, the Antora playbook will fetch the develop branch of each documentation component.
-====
-
-To simplify the process of setting these attributes, you should use the `sitedoc.sh` script.
-Let us generate the `develop` and `master` versions of the documentation:
-
-[source,bash]
-----
-./sitedoc.sh develop
-----
-
-or
-
-[source,bash]
-----
-./sitedoc.sh master
-----
-
-[source,console]
-----
-Site generation complete!
-Open file:///home/user/path/to/antora/build/develop/doc in a browser to view your site.
-Site generation complete!
-Open file:///home/user/path/to/antora/build/doc in a browser to view your site.
-----
-
-== Generating the library documentation
 
 The process for generating the documentation for all libraries is similar.
+However, the components are defined in the `libs.playbook.yml` file and their URLs are relative to the `boostorg` organization.
 Each library documentation is defined as a component in the playbook file `libs.playbook.yml`:
 
 [source,yml]
 ----
 content:
   sources:
-  - url: https://github.com/cppalliance/user-guide
+    - url: https://github.com/boostorg/url
-    start_path: antora
+      start_path: doc
-  - url: https://github.com/vinniefalco/mp11
-    start_path: antora
   # ...
 ----
 
-To simplify the process of setting attributes, you should use the `libdoc.sh` script:
-
-[source,bash]
-----
-./libdoc.sh develop
-./libdoc.sh master
-----
-
-[source,console]
-----
-Site generation complete!
-Open file:///home/user/path/to/antora/build/develop/libs/index.html in a browser to view your site.
-Site generation complete!
-Open file:///home/user/path/to/antora/build/master/libs/index.html in a browser to view your site.
-----
-
 The complete `libdoc.sh` command syntax is:
 
 [source,console]
@@ -192,9 +214,9 @@ with the most recent Antora UI. This command iterates each playbook in the `hist
 
 The master/develop branches of the library documentation are designed to co-exist alongside the per-release documentation and thus the branch name (or release version) does appear in its URLs.
 
-== Working on a single component
+== Component Layout
 
-Each Antora-enabled library includes the https://docs.antora.org/antora/latest/organize-content-files/[component version descriptor file] `antora/antora.yml`.
+Each Antora-enabled library includes the https://docs.antora.org/antora/latest/organize-content-files/[component version descriptor file] `doc/antora.yml`.
 Each library should contain an `antora.yml` describing the component.
 For instance,
 
@@ -207,61 +229,239 @@ nav:
   - modules/ROOT/nav.adoc
 ----
 
-By checking `antora/antora.yml` and the `modules` directory into git, the repository is identified as an Antora content source, which can be listed in `libs.playbook.yml` of this repository.
+After defining the `doc/antora.yml` file, the source files should be organized in the `modules` directory.
-When working locally on an individual component, it's the developers responsibility to adjust and maintain a local playbook.
+Typically, `doc/modules/ROOT/nav.adoc` is the main navigation file for the library documentation and `doc/modules/ROOT/pages/index.adoc` is the main page.
+You can find more information about the https://docs.antora.org/antora/latest/component-version-descriptor/[Component Version Descriptor,window=_blank] and https://docs.antora.org/antora/latest/page/[Pages,window=_blank] in the Antora documentation.
 
-=== Adjusting the local playbook
+Once these files are in place, the library can be registered as a component in the `libs.playbook.yml` file with a Pull Request to the `website-v2-docs` repository:
-
-To render the documentation locally using the local filesystem.
-Modify and include a local version of `lib.playbook.yml` as `local.playbook.yml` for your repository.
-
-==== Boost library candidates
-
-When writing a Boost library proposal, include your library in the local playbook.
-For instance, supposed you are proposing a boost library installed in the `boost/libs`
-directory:
 
 [source,yml]
 ----
-- url: /boost/libs/proposed-lib
+content:
-  start_path: antora
+  sources:
+  # ...
+    - <library-name>: https://github.com/boostorg/<library-name>
+      start_path: doc
 ----
 
-==== Boost libraries
+== Local playbooks
 
-When working on an existing Boost library, the `url` field cannot be set to `/path/to/boost/libs/my_library`
+When working locally on an individual component, it's usually desirable to create a local playbook for your project so that you can render the documentation locally for a single component.
-because the subdirectories of `boost/libs` are submodules.
+The local playbook is a copy of the main playbook that removes all components except the one you are working on.
-Instead, change the URL for one or more content sources to point to the boost superproject and adjust the start path accordingly:
+
+For instance, you can create a copy of `libs.playbook.yml` as `doc/local-playbook.yml`, remove all components except the one you are working on, and adjust the component URL to point to your local filesystem:
 
 [source,yml]
 ----
-- url: /path/to/boost
+# ...
-  start_path: libs/existing-lib/antora
+content:
+  sources:
+    - url: ..
+      start_path: doc
+      edit_url: 'https://github.com/boostorg/<library-name>/edit/{refname}/{path}'
+# ...
 ----
 
-This local version will include your repository only.
+This way, you can render the documentation locally for your component without having to render the entire Boost documentation:
-Run `npx antora --fetch playbook.yml` and similar antora commands described above to build the docs.
 
-- See https://docs.antora.org/antora/latest/install-and-run-quickstart/
+[source,bash]
-- The output automatically goes in `build/site/`
+----
+$ npx antora --fetch local-playbook.yml
+----
 
-=== To Configure Antora Documentation to Remove Left-Side Navigation
+When writing a Boost library proposal, include your library in this local playbook.
 
-This section explains how to to configure an Antora documentation site to remove left-side navigation. 
+== Antora Extensions
 
-The options are set in a playbook.yml file. For `sitedocs` documentation the file is `website-v2-docs/site.playbook.yml`. For library playbooks the file is `website-v2-docs/libs.playbook.yml`.
+// Antora provides an event-based extension facility you can tap into to augment or influence the functionality of the generator
 
-To remove the left-side navigation bar and instead include the table of contents (TOC) in the index.adoc page, include this yml code:
+Antora supports https://docs.antora.org/antora/latest/extend/extensions/[extensions,window=_blank] that can be used to augment the functionality of the generator.
+The playbooks in the `website-v2-docs` repository include a number of extensions that are available to all components.
+
+=== {cpp} Tagfiles Extension
+
+The https://www.npmjs.com/package/@cppalliance/antora-cpp-tagfiles-extension[@cppalliance/antora-cpp-tagfiles-extension,window=_blank] extension allows components to include links to {cpp} symbols defined in the library or external libraries.
+
+For instance, `cpp:std::string[]` will generate a link to the `std::string` symbol in the documentation.
+Note that after the `cpp:` prefix from custom inline macros, the syntax is similar to the one used to generate regular links in AsciiDoc, where the link is replaced by the symbol name.
+
+The link for each symbol is generated from a tagfile provided by the main playbook or by the extension.
+The playbook can define tagfiles for other libraries by including the `cpp-tagfiles` field in the extension configuration:
 
 [source,yml]
 ----
-# Remove the sidenav and include a TOC in the index.adoc page 
+antora:
- remove-sidenav: ''
+  extensions:
+    # ...
+    - require: '@cppalliance/antora-cpp-tagfiles-extension'
+      cpp-tagfiles:
+        files:
+          - file: ./doc/tagfiles/boost-url-doxygen.tag.xml
+            base_url: 'xref:reference:'
+          - file: ./doc/tagfiles/boost-system-doxygen.tag.xml
+            base_url: https://www.boost.org/doc/libs/master/libs/system/doc/html/
+        using-namespaces:
+          - 'boost::'
+    # ...
 ----
 
-By default, the setting is disabled. Setting `remove-sidenav` to any string (including the empty string) enables it.
+Note that the `files` field is a list of tagfiles that are used to generate links to symbols in the documentation.
+These tagfiles can be generated by other tools like Doxygen or MrDocs.
+In some cases, users might want to write their own tagfiles to include symbols from other libraries.
+As tagfiles only describe relative links to symbols, the `base_url` field is used to generate the full URL to the symbol.
 
-The setting applies to all components of the playbook. There is no option to enable/disable it for any specific component of the playbook.
+Also note the `using-namespaces` field, which is a list of namespaces that are used to generate links to symbols in the documentation.
+In the example above, `cpp:small_vector[]` will generate a link to the `boost::small_vector` symbol in the documentation unless there's a tagfile that defines a symbol with the same name in the global namespace.
 
+Each component can also define its own tagfiles by including the `cpp-tagfiles` field in the component descriptor file:
 
+[source,yml]
+----
+ext:
+  cpp-tagfiles:
+      files:
+        - file: ./doc/tagfiles/boost-url-doxygen.tag.xml
+          base_url: 'xref:reference:'
+        - file: ./doc/tagfiles/boost-system-doxygen.tag.xml
+          base_url: https://www.boost.org/doc/libs/master/libs/system/doc/html/
+        - file: ./doc/tagfiles/boost-core-doxygen.tag.xml
+          base_url: https://www.boost.org/doc/libs/master/libs/core/doc/html/
+        - file: ./doc/tagfiles/boost-filesystem-doxygen.tag.xml
+          base_url: https://www.boost.org/doc/libs/master/libs/filesystem/doc/
+      using-namespaces:
+        - boost::urls
+        - boost::urls::grammar
+        - boost::system
+        - boost::core
+----
 
+Files and namespaces defined in components are only applied to that component.
+
+More information about the extension can be found in https://github.com/cppalliance/antora-cpp-tagfiles-extension[its repository,window=_blank] and issues should be reported in https://github.com/cppalliance/antora-cpp-tagfiles-extension/issues[its issue tracker,window=_blank].
+
+=== {cpp} Reference Extension
+
+The https://www.npmjs.com/package/@cppalliance/antora-cpp-reference-extension[@cppalliance/antora-cpp-reference-extension,window=_blank] extension generates reference documentation for {cpp} symbols in your codebase and creates an Antora module with its pages.
+The asciidoc documentation pages are generated with MrDocs and populated in the `reference` Antora module.
+
+This means, the generated reference pages can be linked in your `doc/modules/ROOT/nav.adoc` file as:
+
+[source,adoc]
+----
+// ...
+* Reference
+** xref:reference:index.adoc[]
+// ...
+----
+
+To enable the extension for your component, include the extension configuration in the `antora.yml` file:
+
+[source,yml]
+----
+# ...
+ext:
+  cpp-reference:
+    config: doc/mrdocs.yml
+# ...
+----
+
+The `mrdocs.yml` file will typically include parameters to generate a `compile_commands.json` file used to generate the reference documentation.
+For more information about MrDocs and configuration files, see https://www.mrdocs.com/docs[window=_blank].
+
+The process to generate `compile_commands.json` typically depends on third-party libraries used to compile the project.
+In the case of Boost libraries, other Boost libraries should be available to the command that generates the `compile_commands.json` file.
+The dependencies available to components are defined in the `libs.playbook.yml` file.
+
+[source,yml]
+----
+antora:
+  extensions:
+    - require: '@cppalliance/antora-cpp-reference-extension'
+      dependencies:
+        - name: 'boost'
+          repo: 'https://github.com/boostorg/boost.git'
+          tag: 'develop'
+          variable: 'BOOST_SRC_DIR'
+          system-env: 'BOOST_SRC_DIR'
+----
+
+The extension will download each dependency defined in this list and expose it to the MrDocs environment via the environment variable defined in `variable`.
+If the library is already available in the system, the `system-env` field can be used to expose it to Antora, so it uses this existing path instead of downloading the library.
+
+More information about the extension can be found in https://github.com/cppalliance/antora-cpp-reference-extension[its repository,window=_blank] and issues should be reported in https://github.com/cppalliance/antora-cpp-reference-extension/issues[its issue tracker,window=_blank].
+
+=== Boost Links Extension
+
+The https://www.npmjs.com/package/@cppalliance/asciidoctor-boost-links[@cppalliance/asciidoctor-boost-links,window=_blank] extension allows component pages to include links to Boost libraries and tools.
+For instance:
+
+[source,asciidoc]
+----
+boost:core[]
+----
+
+This will render as if the equivalent AsciiDoc code was used:
+
+[source,asciidoc]
+----
+https://www.boost.org/libs/core[Boost.Core]
+----
+
+When processed by Asciidoc, this renders as "https://www.boost.org/libs/core[Boost.Core]":
+
+[source,html]
+----
+<a href="https://www.boost.org/libs/core">Boost.Core</a>
+----
+
+The extension supports Boost libraries and tools.
+When no custom text is provided, the extension will use the library name in `PascalCase` as the link text.
+When a Boost author has a preference for a different default link text, these are implemented directly in the extension.
+
+More information about the extension can be found in https://github.com/cppalliance/asciidoctor-boost-links[its repository,window=_blank] and issues should be reported in https://github.com/cppalliance/asciidoctor-boost-links/issues[its issue tracker,window=_blank].
+
+=== Playbook Macros Extension
+
+The https://www.npmjs.com/package/@cppalliance/antora-playbook-macros-extension[@cppalliance/antora-playbook-macros-extension,window=_blank] extension allows playbooks to include macros that can be used to generate content in the playbook.
+Each macro has a default value that can be overridden with environment variables, the Antora `--attribute` command line option, or directly in the playbook with the `asciidoc.attributes` field.
+
+The macro is used to implement the branch functionality described in section <<running-antora>>.
+More information about the extension can be found in https://github.com/cppalliance/antora-playbook-macros-extension[its repository,window=_blank] and issues should be reported in https://github.com/cppalliance/antora-playbook-macros-extension/issues[its issue tracker,window=_blank].
+
+== Antora UI Bundle
+
+Each Antora playbook includes a UI bundle that defines the layout of the documentation.
+
+[source,yaml]
+----
+ui:
+  bundle:
+    url: ./antora-ui/build/ui-bundle.zip
+    snapshot: true
+----
+
+This provides a consistent layout across all components of the playbook.
+
+The source code for the UI bundle is located in the `antora-ui` directory of the repository.
+
+The bundle includes a few options to customize the Boost UI by setting the following options in the main playbook:
+
+[source,yaml]
+----
+asciidoc:
+  attributes:
+    # Enable pagination
+    page-pagination: ''
+    # Remove the sidenav and include TOC in index.adoc page
+    remove-sidenav: ''
+    # Include the contents panel with the TOC for the current page
+    page-toc: ''
+----
+
+By default, all options are disabled.
+Setting the options to any string (including the empty string) enables it.
+This is a convention used by Antora to enable/disable options in bundles.
+
+The settings defined in the playbook apply to all documentation components.
+
+The UI bundle documentation is available in the `antora-ui/README.adoc` file. This file describes the structure of the UI bundle and how to customize it.

contributor-guide/modules/ROOT/nav.adoc

@@ -51,10 +51,11 @@ Official repository: https://github.com/boostorg/website-v2-docs
 ** xref:superproject/library-workflow.adoc[]
 
 * Writing Documentation
-** xref:docs/documentation-guidelines.adoc[]
+** xref:docs/layout.adoc[]
-** xref:docs/documentation-components.adoc[]
+** xref:docs/content.adoc[]
+** xref:docs/components.adoc[]
 ** xref:docs/antora.adoc[Antora Guide]
-** xref:docs/asciidoc-style-guide.adoc[]
+** xref:docs/asciidoc.adoc[]
 ** xref:docs/logo-policy-media-guide.adoc[]
 
 * Releases

contributor-guide/modules/ROOT/pages/contributor-community-introduction.adoc

@@ -9,19 +9,26 @@ Official repository: https://github.com/boostorg/website-v2-docs
 = Introduction to the Contributor Community
 :navtitle: Introduction
 
-The Boost Contributors Community is a dedicated group of developers and enthusiasts committed to advancing the Boost libraries. There are many different ways of xref:getting-involved.adoc[] with this community.
+The Boost Contributors Community is a dedicated group of developers and enthusiasts committed to advancing the Boost libraries.
+There are many different ways of xref:getting-involved.adoc[] with this community.
 
 == Communications
 
-The https://lists.boost.org/mailman/listinfo.cgi/boost[Boost Developers Mailing List] is focused on the development and maintenance of the libraries. It is a platform for proposing new libraries, discussing design and implementation details, and coordinating efforts among contributors. Participation in these mailing lists is open to all. In addition to mailing lists, the Boost community also leverages https://slack.com/[Slack] for real-time communication. The Slack Workspace hosts various channels dedicated to specific libraries, general discussions, and coordination among contributors.
+The https://lists.boost.org/mailman/listinfo.cgi/boost[Boost Developers Mailing List] is focused on the development and maintenance of the libraries.
+It is a platform for proposing new libraries, discussing design and implementation details, and coordinating efforts among contributors.
+Participation in these mailing lists is open to all.
+In addition to mailing lists, the Boost community also leverages https://slack.com/[Slack] for real-time communication.
+The Slack Workspace hosts various channels dedicated to specific libraries, general discussions, and coordination among contributors.
 
-When discussing Boost-related topics on social media, contributors are encouraged to follow our xref:tweeting.adoc[Tweeting] guidelines. These guidelines help ensure that the community maintains a positive and informative presence on social media.
+When discussing Boost-related topics on social media, contributors are encouraged to follow our xref:tweeting.adoc[Tweeting] guidelines.
+These guidelines help ensure that the community maintains a positive and informative presence on social media.
 
 New library developers usually have a lot of questions on their mind, before asking for help or information refer to the xref:contributors-faq.adoc[] for answers to many common questions and dilemmas.
 
 == Documentation Style
 
-A consistent documentation style, that emphasizes readability and accessibility, is encouraged. This includes all the library xref:docs/documentation-guidelines.adoc[Documentation Guidelines] and contributions to this website (refer to xref:site-docs-style-guide.adoc[]).
+A consistent documentation style, that emphasizes readability and accessibility, is encouraged.
+This includes all the library xref:docs/layout.adoc[Documentation Guidelines] and contributions to this website (refer to xref:site-docs-style-guide.adoc[]).
 
 == See Also
 

contributor-guide/modules/ROOT/pages/contributors-faq.adoc

@@ -236,7 +236,7 @@ Here are some of the most notable ones:
 
 . *What mitigation strategies have Boost library authors employed to mitigate these unpleasant surprises?*
 +
-Primarily implementing a comprehensive xref:testing/boost-test-matrix.adoc[Test Matrix] to catch issues early. xref:testing/continuous-integration.adoc[Continuous Integration (CI)] systems ensure consistent builds and tests across multiple platforms and configurations. Also actively engaging with the community through forums, mailing lists, and GitHub to gather feedback and address issues promptly. Last but not least, investing time in writing clear, detailed xref:docs/documentation-guidelines.adoc[Documentation] and tutorials to help users get started and understand complex features.
+Primarily implementing a comprehensive xref:testing/boost-test-matrix.adoc[Test Matrix] to catch issues early. xref:testing/continuous-integration.adoc[Continuous Integration (CI)] systems ensure consistent builds and tests across multiple platforms and configurations. Also actively engaging with the community through forums, mailing lists, and GitHub to gather feedback and address issues promptly. Last but not least, investing time in writing clear, detailed xref:docs/layout.adoc[Documentation] and tutorials to help users get started and understand complex features.
 +
 After the initial release, consider releasing regular updates to address bugs, improve performance, and add features as necessary, based on user feedback. Refer to xref:version-control.adoc[].
 +

contributor-guide/modules/ROOT/pages/docs/asciidoc.adoc

@@ -300,4 +300,4 @@ image::filename.png[caption="Figure 1: caption", alt="alternate text"]
 == See Also
 
 * https://mrduguo.github.io/asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
-* xref:site-docs-style-guide.adoc[]
+* xref:site-docs-style-guide.adoc[]

contributor-guide/modules/ROOT/pages/docs/content.adoc

@@ -6,58 +6,37 @@ 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
+= Documentation Content Structure
-:navtitle: Guidelines
+:navtitle: Content
 
-This section covers how to structure library documentation.
+It is not a _requirement_ for a Boost library for the documentation to adhere to the following structure.
+However, it is listed here as a guide, if needed.
 
-== Location
+The following structure for Boost library documentation should work for most libraries.
+Take each section in the order listed below, and fill in the details for your library.
+Alternatively, if you want your documentation to be closer to the pass:[C++] Standard, refer to xref:docs/components.adoc[].
 
-The target location for completed and published library documentation should match the following:
+Although library documentation can use any format in
-
+xref:docs/layout.adoc#standalone-documentation[standalone documentation], the instructions on this page will use AsciiDoc as the format.
-[source,asciidoc]
+Visit https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference,window=_blank] for more information on AsciiDoc syntax.
-----
-https://www.boost.org/doc/libs/<VERSION>/libs/<LIBRARY NAME>/doc/html/index.html
-----
-
-For example:
-
-[source,asciidoc]
-----
-https://www.boost.org/doc/libs/1_81_0/libs/json/doc/html/index.html
-https://www.boost.org/doc/libs/1_82_0/libs/serialization/doc/index.html
-https://www.boost.org/doc/libs/1_83_0/libs/beast/doc/html/index.html
-----
-
-== 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.
-
-== Recommended Structure
-
-It is not a _requirement_ for a Boost library for the documentation to adhere to the following structure. However, it is listed here as a guide, if needed.
-
-The following structure for Boost library documentation should work for most libraries. Take each section in the order listed below, and fill in the details for your library. Alternatively, if you want your documentation to be closer to the pass:[C++] Standard, refer to xref:docs/documentation-components.adoc[].
-
-The format for documentation on the new website is https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference].
 
 Where you see `<LibraryName>` in the templates below, replace with the name of your library.
 
-=== Overview 
+== Overview
 
 Provide a brief overview of the focus and features of your library.
 
-Mention the portability of the library, platforms and compilers. List dependencies.
+Mention the portability of the library, platforms and compilers.
+List dependencies.
 
 A developer should have a good idea if the library is right for their project, after reading your Overview.
 
 Note that footnote references link to the footnotes section, and the entries in the footnote section link back to the references.
 
-==== Overview Template
+=== Overview Template
 
 [source,asciidoc]
 ----
-
 == Overview
 
 Add an introduction to your library here. Refer to previous libraries on the content of an Overview.
@@ -78,7 +57,6 @@ text that requires a footnote. link:#footnote2[(2)]
 
 text
 
-
 == Footnotes
 
 [#footnote1]
@@ -89,11 +67,12 @@ link:#footnote2-location[(2)]: footnote 2 text
 
 ----
 
-=== Rationale 
+== Design Rationale
 
-A Rationale provides a description of the motivation behind the library. Describe the current problems that exist, and the goals of the library in addressing those problems.
+A Rationale provides a description of the motivation behind the library.
+Describe the current problems that exist, and the goals of the library in addressing those problems.
 
-==== Rationale Template
+=== Rationale Template
 
 [source,asciidoc]
 ----
@@ -129,11 +108,11 @@ link:#footnote2-location[(2)]: footnote 2 text
 
 ----
 
-=== Guide
+== Guide
 
 The contents of the guide should be enough to get a new user up and running with your library.
 
-==== Guide Template
+=== Guide Template
 
 [source,asciidoc]
 ----
@@ -154,12 +133,11 @@ text
 text
 ----
 
-
+== Reference
-=== Header 
 
 Provide a complete API reference to your library, without duplicating the contents of the <<Configuration>> or <<Definitions>> sections, which follow.
 
-==== Header Template
+=== Reference Template
 
 [source,asciidoc]
 ----
@@ -377,12 +355,14 @@ function1
 
 ----
 
+If your documentation is defined as an Antora component, the `@cppalliance/antora-cpp-reference-extension` extension can be used to generate the reference documentation from the source code.
+Refer to xref:docs/antora.adoc[] for more details.
 
-=== Configuration
+== Configuration
 
 Describe the configuration macros that are used in your library.
 
-==== Configuration Template
+=== Configuration Template
 
 [source,asciidoc]
 ----
@@ -440,13 +420,14 @@ These are the macros that may be defined by an application using `<LibraryName>`
 |`mult(x,y)` | The x and Y values are multiplied together.
 |===
 
-=== Definitions
+== Definitions
 
-If you library uses any terminology that might benefit from a description, consider adding Definitions to your documentation.
+If your library uses any terminology that might benefit from a description, consider adding a "Definitions" page to your documentation.
 
-Note that each definition is preceded by an anchor, so can be linked to from any other section of your documentation. This can help reduce duplication of explanations - link to your definitions rather than repeat explanations.
+Each definition is typically preceded by an anchor, so can be linked to from any other section of your documentation.
+This can help reduce duplication of explanations: link to your definitions rather than repeat explanations.
 
-==== Definitions Template
+=== Definitions Template
 
 [source,asciidoc]
 ----
@@ -471,18 +452,19 @@ Example:: Assume there is a String-Container library, and that String container
 +
 [#Finder Concept]
 *Finder Concept*::
-A Finder is a function which searches for an arbitrary part of a container. For example (add example logic here).
+A Finder is a function which searches for an arbitrary part of a container.
+For example (add example logic here).
 +
 [#Formatter Concept]
 *Formatter Concept*::
-Formatters are used by string replace algorithms. For example (add example logic here).
+Formatters are used by string replace algorithms.
+For example (add example logic here).
 
-=== Advanced Topics
+== Advanced Topics
 
-Advanced topics include advanced tutorials or examples, and also covers porting, customization, synchronization, and performance tuning.
+Advanced topics include advanced tutorials or examples, and also cover porting, customization, synchronization, and performance tuning.
 
-
+=== Advanced Topics Template
-==== Advanced Topics Template
 
 [source,asciidoc]
 ----
@@ -518,8 +500,7 @@ text
 
 ----
 
-
+== Frequently Asked Questions (FAQs)
-=== Frequently Asked Questions (FAQs) 
 
 A Frequently Asked Questions (FAQ) section might add value to your documentation, by aiding developers with answers to known issues or complexities.
 
@@ -527,7 +508,7 @@ If there are a large number of questions and answers, group them into sections w
 
 Note that every question is in bold, and always ends with a question mark.
 
-==== FAQ Template
+=== FAQ Template
 
 [source,asciidoc]
 ----
@@ -542,7 +523,7 @@ answer1
 answer2
 ----
 
-Example:: 
+Example::
 +
 *Does this library work with COM methods?*
 +
@@ -552,19 +533,21 @@ Yes, if you add `#define BOOST_ENABLE_STDCALL` to your code.
 +
 No, the only supported versions of Windows supported are 10 and 11.
 
-=== Versioning and Release Notes
+== Versioning and Release Notes
 
-Make sure to version your library correctly, and provide release notes for each release. Refer to xref:version-control.adoc[] and xref:release-notes.adoc[] for details.
+Make sure to version your library correctly, and provide release notes for each release.
+Refer to xref:version-control.adoc[] and xref:release-notes.adoc[] for details.
 
-=== Bibliography 
+== Bibliography
 
 If bibliographic references are required in your documentation for your library, add a bibliography to the documentation.
 
-The book title can be text, or can be a link to a site too if the text of the book is available online. The ISBN number can be replaced by another reference number if the reference is to an academic paper, or other reference that is not published in book form.
+The book title can be text, or can be a link to a site too if the text of the book is available online.
+The ISBN number can be replaced by another reference number if the reference is to an academic paper, or other reference that is not published in book form.
 
 Ideally, list the bibliography in alphabetical order.
 
-==== Bibliography Template
+=== Bibliography Template
 
 [source,asciidoc]
 ----
@@ -573,15 +556,16 @@ Ideally, list the bibliography in alphabetical order.
 [Surname/s] Authors full names. _Book title_. ISBN number, Publication date.
 ----
 
-Example:: [Turcan, Wasson] Peter Turcan, Mike Wasson. _Fundamentals of Audio and Video Programming for Games_. ISBN: 073561945X, 2003.
+Example:: [Turcan, Wasson] Peter Turcan, Mike Wasson. _Fundamentals of Audio and Video Programming for Games_.
+ISBN: 073561945X, 2003.
 
+== Acknowledgements
 
+If acknowledgements are required for your library, add an acknowledgements section to the documentation.
+As a rule of thumb, the acknowledgements should be ordered with the most important contributions coming first.
+Links can be included, if required.
 
-=== Acknowledgements
+=== Acknowledgements Template
-
-If acknowledgements are required for your library, add an acknowledgements section to the documentation. As a rule of thumb, the acknowledgements should be ordered with the most important contributions coming first. Links can be included, if required.
-
-==== Acknowledgements Template
 
 [source,asciidoc]
 ----
@@ -602,15 +586,15 @@ Example:: The author appreciates the contributions to the library made by the fo
 * John Doe for input on the architecture and design of the API interfaces.
 * Jane Doe for numerous improvements and suggestions on the text of the error messages.
 
-=== Other Appendices
+== Other Appendices
 
-If any other appendices are needed, add them here. 
+If any other appendices are needed, add them here.
 
 == See Also
 
-* xref:docs/asciidoc-style-guide.adoc[]
+* 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_.
+_Distributed under the Boost Software License, Version 1.0. Refer to http://www.boost.org/LICENSE_1_0.txt_.

contributor-guide/modules/ROOT/pages/docs/layout.adoc

@@ -0,0 +1,107 @@
+////
+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_.

contributor-guide/modules/ROOT/pages/requirements/library-requirements.adoc

@@ -31,7 +31,7 @@ To avoid a proposed library being rejected, it must meet these requirements:
 
 . The library must come reasonably close to meeting the xref:../design-guide/design-best-practices.adoc[].
 
-. The library must be well documented, refer to xref:../docs/documentation-guidelines.adoc[].
+. The library must be well documented, refer to xref:../docs/layout.adoc[].
 
 . The author must be willing to participate in discussions on the mailing list, and to refine the library accordingly.
 

contributor-guide/modules/ROOT/pages/site-docs-style-guide.adoc

@@ -44,4 +44,4 @@ image::url-style-guide-image.png[]
 
 == See Also
 
-** xref:docs/asciidoc-style-guide.adoc[]
+** xref:docs/asciidoc.adoc[]