Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
85 lines (66 loc) · 3.25 KB

CONTRIBUTING.md

File metadata and controls

85 lines (66 loc) · 3.25 KB

Contributing to the Boost.Graph documentation

The docs are built with Antora from AsciiDoc sources under doc/modules/ROOT/.

Layout

Where What
doc/modules/ROOT/pages/ All .adoc pages (organized by topic)
doc/modules/ROOT/examples/ One .cpp per page; the build script captures stdout into a sibling .txt
doc/modules/ROOT/nav.adoc Left-side navigation tree
doc/templates/ Starter templates: algorithm.adoc, generator.adoc, graph_class.adoc — copy and fill in
doc/playbook.yml Antora playbook (UI bundle, content sources)
doc/modules/ROOT/examples/Jamfile b2 rules that compile every example and snapshot its stdout into a sibling .txt
doc/build_example_outputs.sh g++-only fallback that does the same thing as the Jamfile, for contributors without a boost-root checkout

Adding a new page

  1. Pick a template in doc/templates/ and copy it into the right pages/ subdirectory.
  2. Replace the placeholders (title, signatures, parameter table). Keep the section order from the template so the page is consistent with the rest.
  3. Add an .cpp example under modules/ROOT/examples/ at the path the page's include::example$…[] directive points to.
  4. Add an xref: line to doc/modules/ROOT/nav.adoc.

Building locally

The example outputs are generated by b2 (the standard Boost build system). From a boost-root layout:

# 1) Compile every example and snapshot its stdout into a sibling .txt.
b2 libs/graph/doc/modules/ROOT/examples

# 2) Build the static site.
cd libs/graph
npx antora doc/playbook.yml

# 3) Open the result.
open doc/build/site/index.html       # macOS
xdg-open doc/build/site/index.html   # Linux

CI runs the same commands on every push.

Quick fallback (no boost-root required)

For doc-only contributors who only want to fix typos and don't have a boost-root checkout, a shell-script equivalent is provided:

BOOST_INCLUDE=/path/to/boost/include \
BOOST_LIB=/path/to/boost/lib \
bash doc/build_example_outputs.sh

Functionally equivalent to step 1 above; uses g++ directly instead of b2. BOOST_LIB is only needed for the three link-required examples (io/graphml.cpp, io/graphviz.cpp, algorithms/isomorphism/isomorphism.cpp).

Conventions

  • Examples first. == Example (with *Expected output:* block) goes immediately after *Defined in:* so readers see working code before signatures.
  • Bold metadata. *Complexity:*, *Defined in:*, *Expected output:* are bold.
  • Output blocks use [,text]\n---- (same listing-block wrapper as the code above) and pull from the .txt sidecar via include::example$…[], so the documentation can never drift from the code and the two blocks align vertically on the page.
  • Heading levels: == for top-level sections; === only for numbered overloads or grouped variants. The ''' thematic break appears only before a ===, never before a ==.
  • Bundled properties preferred over interior tag properties in examples, unless the algorithm requires the tag.

License

By contributing you agree to license your contribution under the Boost Software License 1.0.