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)

[Becheler]

Thank you so much @andrea-cassioli-maersk !

To answer your points:

1. Yes out-of-source documentation drift is real and risky, and already happening on the old documentation. Without MrDocs or Doxygen support we can't really solve it though, as there are so many algorithms. But bringing in-source documentation is another huge work, so I would rather iterate on it later. When MrDocs will be mature, we should be able to replace the manually written reference by an in-source equivalent, extracted by MrDocs. Intuitively I should say it's 2027 work ?
2. How to migrate the existing doc: I don't think it's relevant, in the sense the migration is a one-man work (me lol). Once the migration will be done, it will be straightforward to contribute to edit the documentation (I placed a banner that will rewire contributors to a documentation issue form).
3. Yes, more focused how-to.
   • I plan to write a complete tutorial on how to write a new BGL algorithm.
   • Also maybe an how-to for creating infinite/lazy graphs as in Add support for ephemeral vertexes (lazy graph) #134 ?
   • Any other idea ?
4. How to contribute: I agree, and also I intuitively feel it's more the role of a Github locked discussion. For example we had contributors unfamiliar with the github process, myself did not know what to expect from the PR draft/review process, and I feel this should not be in the technical documentation? 😄

[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

[Becheler]

Thank you @sducomman ! I began integrated your feedback:

• added general visualization on the landing page
• added visualizations on the primitive page
• added a note on math concepts on the primitive page that rewires to the more formal Graph Theory Review page
• reordered the ToC to follow your suggestions

You can see the result live here: https://becheler.github.io/graph/graph/index.html ❤️
PS: I will rework the visitors page at some point, thank you for your patience 😄

[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)

[Becheler]

That is maybe one of the most important feedback from the workshop :) I was initially planning to refine it for months before to ship, but you and others changed my mind. Let's see how it goes, but we hope it should be live soon ❤️