# Contributing to the Boost.Graph documentation

The docs are built with [Antora](https://antora.org) 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/graph-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:

```sh
# 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/graph-playbook.yml

# 3) Open the result.
open doc/html/index.html       # macOS
xdg-open doc/html/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:

```sh
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](http://www.boost.org/LICENSE_1_0.txt).
