////
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
////
= Antora Guide
:idprefix:
:idseparator: -
:leveloffset: +0

== Antora

This tool renders the documentation for Boost modules whose documentation use asciidoc.

== Installing Antora

CAUTION: The workflow may change in the future.

=== Dependencies

Antora requires Node.js:

[source,bash]
----
$ node -v
----

This command should return an active Node.js LTS 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.

[source,bash]
----
$ nvm install --lts
----

=== Install Antora

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]
----
$ npm ci
----

Verify the antora command is now available by running:

[source,bash]
----
$ npx antora -v
----

[source,console]
----
@antora/cli: 3.1.2
@antora/site-generator: 3.1.2
----

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@3.1 @antora/site-generator@3.1
----

[source,bash]
----
$ antora -v
----

[source,console]
----
@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]

== 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:

[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
./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.
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
    start_path: antora
  - 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]
----
Usage: ./libdoc.sh { branch | version | 'release' | 'all' }...

    branch : 'develop' | 'master' | 'release'
    version: [0-9]+ '.' [0-9]+ '.' [0-9]+
    'release': builds master to build/doc/html
    'all': rebuilds develop, master, and every version

Examples:

    ./libdoc.sh develop master      # build develop and master
    ./libdoc.sh 1.83.0              # build tagged version boost-1.83.0
----

The first positional argument is the only parameter, which identifies which version should be built.

* `branch`: valid arguments are `master` or `develop`.
Builds the `master` or `develop` versions of the documentation in `build/master/libs` or `build/develop/libs`.
It checks out all libraries in their `master` or `develop` branches.
* `version`: a semver version, such as `1.82.0` describing a Boost version.
This allows us to generate the documentation content of an old Boost version with the current version of the Antora UI.
* `'release'`: generate the `master` version to `build/doc/html` with the `release` UI layout.
This layout omits the header, Google analytics, and Edit this Page.
This version of the documentation is meant to be distributed with sources files in the Boost release.
* `'all'`: retroactively iterate and generate the documentation for all versions of Boost
with the most recent Antora UI. This command iterates each playbook in the `history` directory.

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

Each Antora-enabled library includes the https://docs.antora.org/antora/latest/organize-content-files/[component version descriptor file] `antora/antora.yml`.
Each library should contain an `antora.yml` describing the component.
For instance,

[source,yml]
----
name: mp11
title: Boost.Mp11
version: ~
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.
When working locally on an individual component, it's the developers responsibility to adjust and maintain a local playbook.

=== Adjusting the local playbook

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
  start_path: antora
----

==== Boost libraries

When working on an existing Boost library, the `url` field cannot be set to `/path/to/boost/libs/my_library`
because the subdirectories of `boost/libs` are submodules.
Instead, change the URL for one or more content sources to point to the boost superproject and adjust the start path accordingly:

[source,yml]
----
- url: /path/to/boost
  start_path: libs/existing-lib/antora
----

This local version will include your repository only.
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/
- The output automatically goes in `build/site/`