Boost.Graph Documentation Got a Facelift: Ship it Or Not ?
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? 2. Is it better than the old documentation ( https://www.boost.org/doc/libs/1\_91\_0/libs/graph/doc/ )? 3. Would you want to see it merged in its current state or did you identify important mistakes we should absolutely fix before merge? Any general complaints not directly related to this PR scope is welcome and will be integrated in future work :) Thank you, Arno
My apologies, the link for the old documentation was broken: https://www.boost.org/doc/libs/1_91_0/libs/graph/doc/ Best, Arno
1. Is the new documentation preview ( https://491.graph.prtest3.cppalliance.org/graph/index.html ) going in the right direction?
This looks to be a significant improvement both functionally and aesthetically. The navigation is far more ergonomic than using browser back to find the table of contents again. The new animations are plain cool. Asciidoc + Antora is they way to go since they are actively maintained. I would totally recommend continuing down this path. Matt
On Tue, Jun 9, 2026 at 8:44 AM Arnaud Becheler via Boost < boost@lists.boost.org> wrote:
Question to the community:
1. Is the new documentation preview ( https://491.graph.prtest3.cppalliance.org/graph/index.html ) going in the right direction? 2. Is it better than the old documentation ( https://www.boost.org/doc/libs/1\_91\_0/libs/graph/doc/ )? 3. Would you want to see it merged in its current state or did you identify important mistakes we should absolutely fix before merge?
Yes, the new docs are a million times better. I didn't proofread anything but it's already a dramatic improvement. Ship it. - Christian
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...
śr., 10 cze 2026 o 22:59 Andrzej Krzemienski <akrzemi1@gmail.com> napisał(a):
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.
Oh, and the original authors from Indiana University need to be listed in the front matter. Regards, &rzej;
Hi people, Thank you so much for your feedback!
The new animations are plain cool.
Thank you Matt. The animation framework is python based, called manim: https://www.manim.community/ and was developed by Grant Sanderson for 3Blue1Brown, one of my favorite math channel: https://www.youtube.com/watch?v=l6DKRf-fAAM . It's very useful to illustrate dynamic graph algorithms. Since the final animation matters more than its underlying python code, I had little scruples generating the python scaffolding with AI, although automatic generation can only get you so far because it has little to no pedagogical/spatial/temporal/esthetic awareness. I keep a library of small scenes that I can reuse across meetups, docs and conferences: https://github.com/Becheler/animations
I would totally recommend continuing down this path.
Noted. Full steam ahead then!
Yes, the new docs are a million times better [...] ship it.
Thank you Christian! Your feedback matters a lot! The ship has sailed !
Absolutely yes! Thank you so much for doing this! It is already way more user friendly and accessible.
Thank you Andrzej, you're welcome! This was a group effort, we can thank the Alliance for the support, Joaquin and Jeremy for their regular advice, contributors and workshop's attendees (Andrea Cassioli, Sylvain Ducomman and others) for useful feedback :)
For instance, I do not see a Reference section
This is a painful WIP. There is a Bibliography page in About > Bibliography (see https://491.graph.prtest3.cppalliance.org/graph/about/bibliography.html ). I just ported the old pattern to the new antora system: one central Bibliography with bibtex-generated references that reference a handful of algorithms (coverage: ~47/108). I am still debating about to make this system less susceptible to rot. References are algorithm-specific: contributors should not have to touch high-level pages when documenting a new specific algorithm contribution. Similarly, a user exploring the high-level documentation doesn't care about the total list of papers, they just want to know which paper was used to implement a given algorithm. So from both ends the reference should be localized on the algorithm page, not library-wide. It is also more self-sustainable, as a Reference section can easily be documented as mandatory in a contribution template. This seems to be the approach adopted by NetworkX, the python graph library. Two things we lack are 1) How to Cite and 2) BGL general references (Lumsdaine these, BGL book etc). Not sure yet where and how to include them. Feedback welcome :)
For instance, I do not see a Reference section
Oopsie I just understand now you mean a flat list of symbols ? Two things worth noting. The page itself is titled with the code spelling (`predecessor_recorder`), it's only the left-nav label that is prose ("Predecessor Recorder"). And the search bar is meant to cover exactly this case: typing `predecessor_recorder` takes you straight to the page, since the identifier is indexed from the heading and body. On bringing back the old flat symbol table (table_of_contents.html): it was actually highly incomplete and it's mixing purposed (flat symbols refs + conceptual navigation), so I'd rather not reinstate it as-is, the search box is the better lookup-by-symbol path going forward. It is also much easier and robust to maintain (new contributors should not have to touch high-level pages to document algorithm-specific symbols). If you ever search a symbol and it doesn't surface, just ping me, that's a much more useful signal than the old list. Long-term I would love to have an automated extraction of such symbols (mrdocs to the rescue), that would solve your question and my worries. Again, feedback welcome.
In the front page, it is not immediately clear that the cool animation actually illustrates what the following code snippet does.
Noted, I will make this more explicit.
In fact, the animation moves so quickly that I do not know what is actually being illustrated. (It is still cool though.)
Noted, I will expand the timing. I was trying to keep the animations under 15 seconds to match the ever-shrinking attention window of my generation and those who follow. Worth reconsidering.
Please do not use `using namespace boost` and instead prefix every function call with `boost::`
Agreeed.
Rename distances/predecessors to distance_storage/predecessor_storage. Then rename dmap/pmap to distance/predecessor.
Beautiful. I will rework the landing page code + animation and keep you updated :) Thanks again people ! Arnaud
Oh, and the original authors from Indiana University need to be listed in the front matter.
Agreed, it's related to the Reference question I mentioned: original authors, the "How to Cite" question, the BGL book etc. What would you personally want to see mentioned and where ? Best, Arno
wt., 16 cze 2026 o 14:02 Arnaud Becheler <arnaud.becheler@gmail.com> napisał(a):
Absolutely yes! Thank you so much for doing this! It is already way more user friendly and accessible.
Thank you Andrzej, you're welcome! This was a group effort, we can thank the Alliance for the support, Joaquin and Jeremy for their regular advice, contributors and workshop's attendees (Andrea Cassioli, Sylvain Ducomman and others) for useful feedback :)
Then let me extend my thanks to the entire team. You have made Boost a better place!
For instance, I do not see a Reference section
Oopsie I just understand now you mean a flat list of symbols ?
Yes, this.
Two things worth noting. The page itself is titled with the code spelling (`predecessor_recorder`), it's only the left-nav label that is prose ("Predecessor Recorder"). And the search bar is meant to cover exactly this case: typing `predecessor_recorder` takes you straight to the page, since the identifier is indexed from the heading and body.
On bringing back the old flat symbol table (table_of_contents.html): it was actually highly incomplete and it's mixing purposed (flat symbols refs + conceptual navigation), so I'd rather not reinstate it as-is, the search box is the better lookup-by-symbol path going forward. It is also much easier and robust to maintain (new contributors should not have to touch high-level pages to document algorithm-specific symbols). If you ever search a symbol and it doesn't surface, just ping me, that's a much more useful signal than the old list. Long-term I would love to have an automated extraction of such symbols (mrdocs to the rescue), that would solve your question and my worries. Again, feedback welcome.
I didn't mean my comment to sound like another request. I thought your request was to verify if nothing is missing relative to the old docs. And I was not able to do this in a short time. I am only grateful that you are doing this.
Oh, and the original authors from Indiana University need to be listed in the front matter.
Agreed, it's related to the Reference question I mentioned: original
authors, the "How to Cite" question, the BGL book etc. What would you personally want to see mentioned and where ?
I think the convention is to put the author names on the landing page. For instance, https://www.boost.org/doc/libs/1_91_0/doc/html/accumulators.html Regards, &rzej;
Hi Andrzej, Thanks for clarifying. I just began integrating your feedback, a preview is available here: https://509.graph.prtest3.cppalliance.org/graph/index.html The video has been lengthened by 1/3 :) Best, Arno On Tue, Jun 16, 2026 at 4:26 PM Andrzej Krzemienski <akrzemi1@gmail.com> wrote:
wt., 16 cze 2026 o 14:02 Arnaud Becheler <arnaud.becheler@gmail.com> napisał(a):
Absolutely yes! Thank you so much for doing this! It is already way more user friendly and accessible.
Thank you Andrzej, you're welcome! This was a group effort, we can thank the Alliance for the support, Joaquin and Jeremy for their regular advice, contributors and workshop's attendees (Andrea Cassioli, Sylvain Ducomman and others) for useful feedback :)
Then let me extend my thanks to the entire team. You have made Boost a better place!
For instance, I do not see a Reference section
Oopsie I just understand now you mean a flat list of symbols ?
Yes, this.
Two things worth noting. The page itself is titled with the code spelling (`predecessor_recorder`), it's only the left-nav label that is prose ("Predecessor Recorder"). And the search bar is meant to cover exactly this case: typing `predecessor_recorder` takes you straight to the page, since the identifier is indexed from the heading and body.
On bringing back the old flat symbol table (table_of_contents.html): it was actually highly incomplete and it's mixing purposed (flat symbols refs + conceptual navigation), so I'd rather not reinstate it as-is, the search box is the better lookup-by-symbol path going forward. It is also much easier and robust to maintain (new contributors should not have to touch high-level pages to document algorithm-specific symbols). If you ever search a symbol and it doesn't surface, just ping me, that's a much more useful signal than the old list. Long-term I would love to have an automated extraction of such symbols (mrdocs to the rescue), that would solve your question and my worries. Again, feedback welcome.
I didn't mean my comment to sound like another request. I thought your request was to verify if nothing is missing relative to the old docs. And I was not able to do this in a short time. I am only grateful that you are doing this.
Oh, and the original authors from Indiana University need to be listed in the front matter.
Agreed, it's related to the Reference question I mentioned: original
authors, the "How to Cite" question, the BGL book etc. What would you personally want to see mentioned and where ?
I think the convention is to put the author names on the landing page. For instance, https://www.boost.org/doc/libs/1_91_0/doc/html/accumulators.html
Regards, &rzej;
sob., 20 cze 2026 o 17:05 Arnaud Becheler <arnaud.becheler@gmail.com> napisał(a):
Hi Andrzej,
Thanks for clarifying. I just began integrating your feedback, a preview is available here: https://509.graph.prtest3.cppalliance.org/graph/index.html The video has been lengthened by 1/3 :)
Thank you! The video pace is definitely more friendly to people from my generation :) The introductory paragraph also makes a huge difference! Upon reading the intro one gets the impression that working with graphs and Boost.Graph is easy! This is a huge contribution to the library. Now, the Compiler Explorer link should be also updated to match the modified example. Regards, &rzej;
Best, Arno
On Tue, Jun 16, 2026 at 4:26 PM Andrzej Krzemienski <akrzemi1@gmail.com> wrote:
wt., 16 cze 2026 o 14:02 Arnaud Becheler <arnaud.becheler@gmail.com> napisał(a):
Absolutely yes! Thank you so much for doing this! It is already way more user friendly and accessible.
Thank you Andrzej, you're welcome! This was a group effort, we can thank the Alliance for the support, Joaquin and Jeremy for their regular advice, contributors and workshop's attendees (Andrea Cassioli, Sylvain Ducomman and others) for useful feedback :)
Then let me extend my thanks to the entire team. You have made Boost a better place!
For instance, I do not see a Reference section
Oopsie I just understand now you mean a flat list of symbols ?
Yes, this.
Two things worth noting. The page itself is titled with the code spelling (`predecessor_recorder`), it's only the left-nav label that is prose ("Predecessor Recorder"). And the search bar is meant to cover exactly this case: typing `predecessor_recorder` takes you straight to the page, since the identifier is indexed from the heading and body.
On bringing back the old flat symbol table (table_of_contents.html): it was actually highly incomplete and it's mixing purposed (flat symbols refs + conceptual navigation), so I'd rather not reinstate it as-is, the search box is the better lookup-by-symbol path going forward. It is also much easier and robust to maintain (new contributors should not have to touch high-level pages to document algorithm-specific symbols). If you ever search a symbol and it doesn't surface, just ping me, that's a much more useful signal than the old list. Long-term I would love to have an automated extraction of such symbols (mrdocs to the rescue), that would solve your question and my worries. Again, feedback welcome.
I didn't mean my comment to sound like another request. I thought your request was to verify if nothing is missing relative to the old docs. And I was not able to do this in a short time. I am only grateful that you are doing this.
Oh, and the original authors from Indiana University need to be listed in the front matter.
Agreed, it's related to the Reference question I mentioned: original
authors, the "How to Cite" question, the BGL book etc. What would you personally want to see mentioned and where ?
I think the convention is to put the author names on the landing page. For instance, https://www.boost.org/doc/libs/1_91_0/doc/html/accumulators.html
Regards, &rzej;
participants (4)
-
Andrzej Krzemienski -
Arnaud Becheler -
Christian Mazakas -
Matt Borland