Convert documentation to Antora

[cmazakas]

build_antora.sh is the hook used by the release scripts to builds the docs. Locally, all one needs to do is npm install --dev && npx antora unordered-playbook.yml

[joaquintides]

build_antora.sh is empty?

[cmazakas]

build_antora.sh is empty?

Ha. Alright, forgot to copy-paste the contents when I made this new branch. Will update the script.

[sdarwin]

• When release scripts build a whole boost archive, they call this script as one of the steps:
  https://github.com/boostorg/website-v2-docs/blob/develop/libdoc.sh

• Then, local docs uses build_antora.sh (if boostorg/url is the example)

[joaquintides]

Would it make sense to have an equivalent build_antora.bat for Windows?

[cmazakas]

Would it make sense to have an equivalent build_antora.bat for Windows?

Sure! I'll add that in too.

[cmazakas]

@sdarwin Hmm, shouldn't we be getting doc previews for this? Did I silently break the bot that does this? I can obviously fix any of the issues that have arisen from this.

[cppalliance-bot]

An automated preview of the documentation is available at https://299.unordered.prtest2.cppalliance.org/index.html

[sdarwin]

Alright, a preview just posted. The job must be customized for b2 or antora.

[joaquintides]

I've gone through all the docs and this is a list of the broken internal links I've detected:

• Introduction
  • See the Equality Predicates and Hash Functions section for more details.
• Basics of Hash Tables
  • There is more information on hash functions and equality predicates in the next section.
• Equality Predicates and Hash Functions
  • For example, boost::unordered_map is declared as:
• Regular Containers
  • See the reference for more details on the rehash function.
• Concurrent Containers
  • Consult the references of boost::concurrent_node_set, boost::concurrent_node_map, boost::concurrent_flat_set and boost::concurrent_flat_map for the complete list of visitation-enabled operations. Links work, but the link for boost::concurrent_node map has concurrent_node_map.html#concurrent_flat_map when it should have concurrent_node_map.html#concurrent_node_map.
• Data Structures
  • Closed-addressing Containers: For more information on implementation rationale, read the corresponding section. Wrongly links to open-addressing section.
• Reference
  • stats. Should be more aptly named "Statistics"
    • number of bucket groups accessed per operation
    • These statistics can be used to determine if a given hash function can be marked as avalanching.
  • using stats = stats-type;
  • If hash_is_avalanching::value is true
  • Only available if statistics calculation is enabled. The links to statistics is broken. Happens everywhere in the reference.
  • Deduction guides: links to iter-value_type broken

[cppalliance-bot]

An automated preview of the documentation is available at https://299.unordered.prtest2.cppalliance.org/index.html

[cppalliance-bot]

An automated preview of the documentation is available at https://299.unordered.prtest2.cppalliance.org/index.html

[k3DW]

I'm wondering about these links at the top right on desktop. On the preview they don't seem to do anything. Are they meant to do something later? Or can they be removed?

I think the "Edit this Page" button is useful to direct anyone to GitHub if they see a mistake or improvement. That button should stay. But I don't see a need for the others.

[joaquintides]

The links to the full-size images in this section are broken:

https://299.unordered.prtest2.cppalliance.org/unordered/benchmarks.html#benchmarks_boostconcurrent_flatnode_map

[cmazakas]

I'm wondering about these links at the top right on desktop. On the preview they don't seem to do anything. Are they meant to do something later? Or can they be removed?
I think the "Edit this Page" button is useful to direct anyone to GitHub if they see a mistake or improvement. That button should stay. But I don't see a need for the others.

This is an artifact of the default Antora UI bundle which should be solved when we use the release one pulled in during the libs.playbook.yml build here:
https://github.com/boostorg/website-v2-docs/blob/develop/libs.playbook.yml

Otherwise, yeah, we can fix this by building our own UI bundle.

[cppalliance-bot]

An automated preview of the documentation is available at https://299.unordered.prtest2.cppalliance.org/index.html

[sdarwin]

Hi @cmazakas , from comments in Slack, not sure if you are intending to switch the methodology back to using b2 and the doc/html folder, while still using antora. And then, not the global playbook? In that case it would create a new, hybrid type of docs. linuxdocs.sh would need to distinguish the situation. A thought comes to mind, rename build_antora.sh to something distinct. Maybe build_b2_antora.sh or similar, so that build_antora.sh has a certain meaning, and build_b2_antora.sh? another one, if such scripts are discovered in various repositories.

[joaquintides]

Build setup:

• doc/index.html redirect file needs be readjusted.
• preview.md and roadmap.md seem to have sneaked in with no purpose.
• Jamfile.v2: we would need a Windows version of run-script.
• build_antora.sh: does it have execution permissions?
• build_antora.sh: what's npm ci for?

[joaquintides]

On mobile devices (tested with an iPhone 8):

• Home --> TOC --> click on "Regular Containers": doesn't jump to the section. A further click is needed. Note the expanding icon on the top right corner appearing after the first click.

• Contents menu: this menu appears OK on all sections (see example) except on the subsections in the reference, see boost::unordered_map for instance.

• boost::concurrent_flat_map::try_emplace: text abnormaly large. I haven't checked all the places where this occurs.

[sdarwin]

build_antora.sh: what's npm ci for?

This is an interesting point. npm ci installs npm packages.

However, the overall design is to have release-tools preinstall packages in the docker image so when ci_boost_release.py builds everything there is less risk of package failure, and it's faster.

From that perspective, we would prefer to avoid:

• each separate library installing packages
• variation of package versions across boost libraries

build_antora.sh was designed for a certain purpose, which is local testing. It has previously never been run with a full release bundle, ci_boost_release.py

Potentially, there could be multiple scripts in unordered/doc/, for local builds, and ci_boost_release.

[cppalliance-bot]

An automated preview of the documentation is available at https://299.unordered.prtest2.cppalliance.org/libs/unordered/doc/html/index.html

[sdarwin]

Open to contributions: allow antora to function with git submodules:

https://github.com/isomorphic-git/isomorphic-git/issues/1647

[cppalliance-bot]

An automated preview of the documentation is available at https://299.unordered.prtest2.cppalliance.org/libs/unordered/doc/html/index.html

[cmazakas]

Build setup:

• doc/index.html redirect file needs be readjusted.
• preview.md and roadmap.md seem to have sneaked in with no purpose.
• Jamfile.v2: we would need a Windows version of run-script.
• build_antora.sh: does it have execution permissions?
• build_antora.sh: what's npm ci for?

I've deleted doc/index.html and preview.md and roadmap.md. doc/index.html must be a relic of previous refactors, it doesn't seem necessary any longer. The main top-level repo's index.html now correctly redirects to: <meta http-equiv="refresh" content="0; URL=doc/html/index.html">

I'm not sure if a Windows version of the script is a blocker for release but I'm hoping @sdarwin can shed some illumination there. As far as I'm aware, the docs generation is done purely via b2 doc in the boost-root in a docker container.

For Windows, there's not much difference between b2 libs/unordered/doc and npx antora unordered-playbook.yml.

The npm ci call is used to install all the dependencies required. It's a variation of npm install --dev but it requires a package-lock.json be present, which is idiomatic for ensuring consistency in regards to dep versions.

[cppalliance-bot]

An automated preview of the documentation is available at https://299.unordered.prtest2.cppalliance.org/libs/unordered/doc/html/index.html

[sdarwin]

• The release process runs on Linux, and shouldn't be blocked by the absence of a Microsoft-Windows-specific script.

• In general, there are some programs that run equally well on Linux and Windows without customization, so a windows version isn't necessary. I don't know how that applies to the updates in this pull request though. Compare to other boost libs.

[cppalliance-bot]

An automated preview of the documentation is available at https://299.unordered.prtest2.cppalliance.org/libs/unordered/doc/html/index.html

[cppalliance-bot]

An automated preview of the documentation is available at https://299.unordered.prtest2.cppalliance.org/libs/unordered/doc/html/index.html