build_docs: add Asciidoctor documentation build support

[julioest]

• enhance build type detection to recognize Asciidoctor documentation
• add 'asciidoctor' as a valid build type
• implement b2 build command for Asciidoctor documentation with source highlighter
• improve variable handling

Resolves boostorg/boostlook#67

[julioest]

Hey @sdarwin. I was able to successfully change the source highlighter. Before I move on to the other 2 files (windows and linux scripts), how's this strategy?

[sdarwin]

When release-tools builds the entire boost bundle, it needs to be capable of building any/all docs, without caring too much if they are asciidoctor, quickbook, etc. They all need to be buildable. The main script which does that is ci_boost_release.py. In ci_boost_release.py it really only distinguishes between two build type: 'antora' which has it's own section of code, and everything else.

You're adding a code change in build_docs. Those are not the main build script, they are shortcut/helper scripts to build one library at a time. The initial aim there was for a boost developer to use build_docs locally on their own computer. Now additionally it's being leveraged by Jenkins for "doc previews".

I think it's better for build_docs to track the functionality of the main build script (ci_boost_release.py), which needs to be able to build "everything", and it doesn't distinguish asciidoctor or not asciidoctor. Therefore, a new "build type" shouldn't be necessary. Just continue to run "b2", as before, on any library. That reduces and simplifies the code.

So how will "asciidoctor-attribute=source-highlighter=highlight.js" be set?

Notice "user-config.jam", which is already in macosdocs.sh. That's a config file that b2 references. Add the new setting into user-config.jam (for all libraries). I believe "user-config.jam" uses a syntax that is very similar to any Jamfile. Therefore, review Jamfiles from any boost repositories, to see examples of syntax. It can't be too difficult to format the setting "asciidoctor-attribute=source-highlighter=highlight.js". If there are difficulties, contact grisumbras or another alliance developers. They are experts in b2.

After the build_docs scripts are working, which is a good first step, ultimately ci_boost_release.py needs to be modified. That will have the real effect on the website.

How to test release-tools locally: https://github.com/boostorg/release-tools/blob/develop/docs/README.md

B2 docs: https://www.bfgroup.xyz/b2/manual/release/index.html

[sdarwin]

Is highlight.js a nodejs module?

The idea with all the build_docs scripts is that they install all pre-reqs.

In terms of ci_boost_release.py, package installation should go in https://github.com/boostorg/release-tools/blob/develop/docker/python3/noble/v3/Dockerfile so it happens once in the Dockerfile, and doesn't need to be repeated on each build.

Create a v4 directory, and a v4/Dockerfile.

Include highlight.js in the existing node/nvm section there.

For build_docs, it's an open question about how to handle this. It's almost persuasive to keep your current $typeoption modifications.

However, here is an idea: asciidoctor won't be a full-fledged type for the moment. Keep the detection logic, but use it to set a new variable asciidoctor_docs="yes", and also set "install_antora_deps" = "yes", whenever asciidoctor is detected.

Actually, asciidoctor_docs="yes" won't be used. It can be be set, as a demonstration.

The variable "install_antora_deps" will be the one that's relevant.

That will trigger this existing section to install npm packages:

if [ "$typeoption" = "antora" ] || [ "$install_antora_deps" = "yes" ]; then

Causing npm packages to get installed.

Create another separate PR that focuses on ci_boost_release.py and Docker. That's what affects the website. And actually it should be done first, before this PR, because Jenkins jobs have a dependency on the docker image.