|
Caution
|
The workflow may change in the future. |
Antora requires Node.js:
$ node -vThis command should return an active Node.js LTS version number:
v16.18.0If you have Node.js installed, but it isn’t an active LTS version, you need to upgrade Node.js.
$ nvm install --ltsAfter cloning the project, you need to install Antora command line interface (CLI) and the Antora site generator describe in the package.json file:
$ npm ciVerify the antora command is now available by running:
$ npx antora -v@antora/cli: 3.1.2
@antora/site-generator: 3.1.2You also have the option of installing Antora globally so that the antora command is available on your PATH.
$ npm i -g @antora/[email protected] @antora/[email protected]$ antora -v@antora/cli: 3.1.2
@antora/site-generator: 3.1.2Read more about antora on their Quickstart guide
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:
npx antora --fetch --attribute boost_version=develop --attribute boost_site_prefix=develop/ site.playbook.ymlThis should build the website in build/develop/doc/.
|
Important
|
Notice the |
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:
./sitedoc.sh developor
./sitedoc.sh masterSite 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.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:
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:
./libdoc.sh develop
./libdoc.sh masterSite 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:
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.0The first positional argument is the only parameter, which identifies which version should be built.
-
branch: valid arguments aremasterordevelop. Builds themasterordevelopversions of the documentation inbuild/master/libsorbuild/develop/libs. It checks out all libraries in theirmasterordevelopbranches. -
version: a semver version, such as1.82.0describing 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 themasterversion tobuild/doc/htmlwith thereleaseUI 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 thehistorydirectory.
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.
Each Antora-enabled library includes the component version descriptor file antora/antora.yml.
Each library should contain an antora.yml describing the component.
For instance,
name: mp11
title: Boost.Mp11
version: ~
nav:
- modules/ROOT/nav.adocBy 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.
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.
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:
- url: /boost/libs/proposed-lib
start_path: antoraWhen 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:
- url: /path/to/boost
start_path: libs/existing-lib/antoraThis 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/
This section explains how to to configure an Antora documentation site to remove left-side navigation.
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.
To remove the left-side navigation bar and instead include the table of contents (TOC) in the index.adoc page, include this yml code:
# Remove the sidenav and include a TOC in the index.adoc page
remove-sidenav: ''By default, the setting is disabled. Setting remove-sidenav to any string (including the empty string) enables it.
The setting applies to all components of the playbook. There is no option to enable/disable it for any specific component of the playbook.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent