doc: reinstate stanford graph base documentation page with example

[Becheler]

Before submitting

• This PR targets the develop branch.
• I searched for an existing PR or issue covering the same change.
• My contribution is licensed under the Boost Software License 1.0.

Type of change

• Bug fix
• New feature or API addition
• Refactor (no behavior change)
• Documentation
• Build, CI, or tooling
• Other (specify below)

Does this PR introduce a breaking change?

• Yes (describe migration impact below)
• No

What this PR does

Reinstate the lost documentation page: https://www.boost.org/doc/libs/1_34_0/libs/graph/doc/stanford_graph.html

Motivation

Testing

Checklist

• Existing tests pass (b2 in the test/ directory).
• New behavior is covered by a test, or this is a docs / build / refactor change.
• Documentation was updated if user-facing behavior changed.
• No new compiler warnings on the platforms I built against.

[github-actions]

Boost dependency footprint vs develop (auto-generated).
PR run 33627134707 vs develop run 33602415333 (6345572040).

Header-inclusion weights (graph files pulling each direct dependency in):

No header-inclusion-weight changes.

Transitive Boost modules: 66 → 66 (0)

[cppalliance-bot]

An automated preview of the documentation is available at https://585.graph.prtest3.cppalliance.org/libs/graph/doc/html/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-09-02 12:01:22 UTC

[github-actions]

Compiler-warning counts vs develop (auto-generated).
PR run 33627134803 vs develop run 33602415345 (6345572040).

Job	Baseline	After	Delta
macos (clang, 14)	648	648	0
macos (clang, 17)	611	611	0
macos (clang, 20)	611	611	0
ubuntu (clang-19, 14)	648	648	0
ubuntu (clang-19, 17)	611	611	0
ubuntu (clang-19, 20)	611	611	0
ubuntu (clang-19, 23)	611	611	0
ubuntu (gcc-14, 14)	801	801	0
ubuntu (gcc-14, 17)	937	937	0
ubuntu (gcc-14, 20)	937	937	0
ubuntu (gcc-14, 23)	937	937	0
windows_msvc_14_3 (msvc-14.3)	961	961	0

[Becheler]

@ascherer the SGB interface documentation is back and available here: https://585.graph.prtest3.cppalliance.org/libs/graph/doc/html/graph/extending/stanford_graph.html

Is there anything you would like to see ? 😄

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ascherer]

@Becheler Thanks for the restauration. I have two annotations:

1. My updated SGB creates a dynamic shared object libgb.so (located at /usr/lib/x86_64-linux-gnu/sgb/libgb.so when installed from sgb_2\:20251228-51_amd64.deb on Kubuntu). Check Using the SGB and Where Defined.
2. Paragraph Missing include guards can be deleted; the modernized SGB has custom include guards for all gb_* modules, e.g., GB_IO_H in sgb/gb_io.h.

I am contemplating to suggest a major change in boost/graph/stanford_graph.hpp: The updated Makefile of SGB places the header files in /usr/include/sgb, so the #include statements in the BGL header could be extended with sgb/ for every gb_* interface. This would spare users from having to give the -I /usr/include/sgb option to the C++ ompiler. (I don't know how to resolve -L /usr/lib/x86_64-linux-gnu/sgb for -lgb automatically. It seems to be a debbuild thing to add the machine type.) WDYT?

[Becheler]

Thank you @ascherer

In the meantime I modernized one minimal example to run in our runnable CI examples doc/module/examples. Examples in BGL have never been exercised by CI and so many have broken along the years. I am not sure we want BGL unit tests to depend on an external dependency, so I left it for documentation CI job only.

I also added a small section describing to users what this SGB page is (not) about.

https://585.graph.prtest3.cppalliance.org/libs/graph/doc/html/graph/extending/stanford_graph.html

About your changes, I would be careful.

I agree that having #include <sgb/gb_graph.h> instead of #include <gb_graph.h> would be cosmetically nicer.

However changing the headers of BGL would break users including our CI since we rely on apt-get package. I could use the new package, but it's more fragile and harder to maintain. I could add a symbolic link in CI to fake the new layout, but that will still break users. If there are now two layouts in the wild, then maybe BGL needs to adapt to both:

#if defined(__has_include) && __has_include(<sgb/gb_graph.h>)
#  // use the sgb/ prefix
#else
#  // use bare names
#endif

Maybe we could add something to it like #warning "the unprefixed SGB header layout is deprecated. Install an SGB that uses <sgb/...>" but it would mean BGL would be deprecating other people's packaging conventions from a downstream header... I don't think it's the right path. Plus the old layout will still remain in Debian unless their maintainers decide differently, right ?

So in conclusion I do think the compatibility shim is the best of two worlds.

[ascherer]

However changing the headers of BGL would break users

Unfortunately, yes. Let's keep the interface intact.

[Becheler]

Unfortunately, yes. Let's keep the interface intact.

@ascherer Sorry if I was not clear, but unless I'm mistaken, this would support both layouts and not break anyone ?
So users would be free to use both packages/layouts and the BGL header adapts ?

#if defined(__has_include) && __has_include(<sgb/gb_graph.h>)
  // use the sgb/ prefix
  #include <sgb/gb_graph.h>
#else
  // use bare names
  #include <gb_graph.h>
#endif

[ascherer]

@Becheler I'm not familiar with __has_include, but GNU has this caveat: https://gcc.gnu.org/onlinedocs/gcc-15.3.0/cpp/_005f_005fhas_005finclude.html

[Becheler]

Good catch. Thinking about it, BGL is now C++14, and supported compiler/platforms (at least those in CI) all support the symbol IIUC.

After looking around, it's also used across Boost Asio and Config:

https://github.com/boostorg/asio/blob/a7dc25b4cb6c49a6946d86ea20664f1027203225/include/boost/asio/detail/config.hpp#L491-L503

https://github.com/boostorg/config/blob/93861f26d575b2952e1af8edd5bf84a1d82163c2/include/boost/config/detail/suffix.hpp#L1156-L1173

[ascherer]

@Becheler As I said, I'm not familiar with __has_include, but cppreference.com lists it as standard from C++17 and as a comforming extension in C++14: https://en.cppreference.com/cpp/preprocessor/include

Anyway, feel free to add the appropriate preprocessor logic in stanford_graph.hpp as you see fit.