Re: Boost.Graph Documentation Got a Facelift: Ship it Or Not ?

wt., 9 cze 2026 o 17:43 Arnaud Becheler via Boost <[email protected]>
napisał(a):

> Dear Boostlings, Graphlings,
>
> We have taken a first step in modernizing the Boost.Graph documentation
> with a preview available here:
> https://491.graph.prtest3.cppalliance.org/graph/index.html .
>
> These first steps aim at solving low-hanging fruits and answering frequent
> complaints from users collected during the 2022 User Survey (
> https://www.reddit.com/r/cpp/comments/vyt4t5/boostgraph_user_survey/ ) and
> BGL workshop 2026  ( https://github.com/boostorg/graph/discussions/466 )
>
> - documentation hard to explore (no table of content, no search bar)
> - examples use old C++ and several don't even compile
> - outdated visual design
>
> We have been investing into several dimensions:
>
> - migrating the old pure html pages to asciidoc + antora
> - modern examples for each algorithm are compiled and run in CI, with
> output integrated in the documentation
> - higher scanability for algorithm complexity + where defined
> - a better landing for users not familiar with property maps
>
> The PR currently sits unmerged as we are trying to assess its viability.
>
> Important:
>
> - this is NOT the final vision, this is meant as a first important step.
> - the current scope is NOT a full rewrite/reorganization of each algorithm
> page (future work).
> - the current scope is a modernization of the documentation infrastructure.
>
> - we are just worried we may have made and missed important mistakes that
> should prevent the merge, so Jeremy Murphy (principal BGL maintainer) and I
> decided to poll around for general review and feeling.
>
> Question to the community:
>
> 1. Is the new documentation preview (
> https://491.graph.prtest3.cppalliance.org/graph/index.html ) going in the
> right direction?
>

Absolutely yes! Thank you so much for doing this!
It is already way more user friendly and accessible.



> 2. Is it better than the old documentation (
> https://www.boost.org/doc/libs/1\_91\_0/libs/graph/doc/ )?
>

The front matter is definitely better.


> 3. Would you want to see it merged in its current state or did you identify
> important mistakes we should absolutely fix before merge?
>

In order to be able to say that it can be merged right now, I would have to
be sure if nothing important didn't disappear from the old one, and I was
not able to inspect it that thoroughly.

For instance, I do not see a Reference section. Old docs also do not have
one either, but I can see
https://www.boost.org/doc/libs/1_91_0/libs/graph/doc/table_of_contents.html
where all names, like  predecessor_recorder
<https://www.boost.org/doc/libs/1_91_0/libs/graph/doc/predecessor_recorder.html>,
are listed. In the new docs, if I knew where to click, I would get to
section "Predecessor Recorder
<https://491.graph.prtest3.cppalliance.org/graph/visitors/predecessor_recorder.html>"
but it is still different spelling: not the one used in code.


> Any general complaints not directly related to this PR scope is welcome and
> will be integrated in future work :)
>

You bet.
In the front page, it is not immediately clear that the cool animation
actually illustrates what the following code snippet does. In fact, the
animation moves so quickly that I do not know what is actually being
illustrated. (It is still cool though.)

The code snippet alone already does a great service to the users, present
and future ones. I would recommend improving it further.
Please do not use `using namespace boost` and instead prefix every function
call with `boost::`. This will make the code a bit longer, but it will make
it clear which parts come from the library, and which are defined in the
fairly long snippet. For instance, in:

```
auto vidx = get(vertex_index, g);
```

It is so difficult to figure out what `vertex_index` is and how it got
there, and  if this example would even compile.  `using namespace` is such
a bad habit, and young developers learn it from looking at library examples
like this one.

The code example will require even more comments. For instance, it is not
clear what 20 is in:

```
Graph g(edges.begin(), edges.end(), 20);
```

Next, in:

```
    // Wrap storage into property maps
    auto vidx = get(vertex_index, g);
    auto dmap = make_iterator_property_map(distances.begin(), vidx);
    auto pmap = make_iterator_property_map(predecessors.begin(), vidx);
```

It is not clear that all three represent property maps. The first one looks
so different from the other two. Why does the first one not have "map" in
the variable name?

Rename distances/predecessors to distance_storage/predecessor_storage. Then
rename dmap/pmap to distance/predecessor.

Regards,
&rzej;



>
> Thank you,
> Arno
> _______________________________________________
> Boost mailing list -- [email protected]
> To unsubscribe send an email to [email protected]
> https://lists.boost.org/mailman3/lists/boost.lists.boost.org/
> Archived at:
> https://lists.boost.org/archives/list/[email protected]/message/SJSPE2T42BPYZSBIXULMDXHPZFF2TI3S/
>
_______________________________________________
Boost mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://lists.boost.org/mailman3/lists/boost.lists.boost.org/
Archived at: https://lists.boost.org/archives/list/[email protected]/message/7XT5X4VMUSRVH7DQMQSINBJWS2FHNMTO/