wt., 9 cze 2026 o 17:43 Arnaud Becheler via Boost <boost@lists.boost.org> 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 -- boost@lists.boost.org To unsubscribe send an email to boost-leave@lists.boost.org https://lists.boost.org/mailman3/lists/boost.lists.boost.org/ Archived at: https://lists.boost.org/archives/list/boost@lists.boost.org/message/SJSPE2T4...