Review the new documentation site

[Becheler]

Story

@Becheler rebuilt BGL's documentation from scratch in Q1 2026 (AsciiDoc + Antora):

• Official documentation: https://www.boost.org/doc/libs/latest/libs/graph/doc/index.html
• New fork: https://becheler.github.io/graph

The new site has:

• Table of content (highly demanded)
• Search bar
• ~108 algorithm pages across 16 families,
• decision tables in every section overview,
• ~152 C++14 examples whose stdout is snapshotted into .txt sidecars the pages include.
• Docs CI rebuilds every example on every push, so compile breaks fail the build (output drift is not yet diffed against a baseline).

The rewrite was fast and broad, so a fresh set of eyes is the best quality gate.

Dream

• New docs become official, legacy HTML is gone.
• Examples stay green, a researcher with no Boost experience can follow the "How to Implement" page
• About and Extending are modernized and accurate

Intermediary objectives

• Navigate as a first-time user solving a real problem. Log every confusion, gap, or wrong assumption.
• Audit 3 to 5 algorithm pages against the source headers and the literature. Flag anything off.
• Read extending/constructing_algorithms.adoc and try to answer "how would I add a new algorithm?". The gaps become the outline for the missing page.

[andrea-cassioli-maersk]

Looks very nice and promising, I wonder how it will integrate with MrDocs. But it is worth the investment.

Very important is the process of updating the docs: what is a bit under the radar is that often the docs gets old and loose alignment. Shall we have a regular checkup?

Examples are fine but take a lot of space maybe should be put at the bottom, and only a snippet at the beginning to explain the usage.

It is crucial to:

• how to migrate the existing docs
• add more focused how-to
• make room for material on how to contribute

Reach 100%
Severity 80% (optimistic)

[sducomman]

This new documentation is more pretty/attractiv than official documentation.
Some commentaries in vrac :

• A documentation of graph librairie has no images of graph... To explain some concept, I think we can made graphics of graph (maybe with mermaid)
• The order of content is quite strange : I will see :
  • General concept (what is a graph, node, edge, description of edges)
  • Graph class (how a graph is representing in memory) with images
  • Graph generator
  • Property maps (explain the property map before presenting algorithms, because some algorithm need property map)
  • Visitor (same)
  • Algorithms
  • For each algo, I prefer see Description before examples
• Page visitor is hard, I think is better to present the concept and how made own visitor. For the rest, see the visitor caracteristic algorithms page. When we use visitor, we had choiced the algorithm, so see the possible visitors in algorithm pages is better.
• Graph adaptator : synopsis before example

[andrea-cassioli-maersk]

One more thing: it does not need to be perfect, as long as there is a way to give feedback and get it fix (also as contribution)