Example Workflow

This workflow describes how to create a new example and integrate it into the project documentation.

Goal

Examples in this repository serve two purposes. They provide small public-facing scripts that show the intended user workflow. They also provide stable command-line output that is published in the Sphinx documentation.

Examples that are shown in the documentation should be concise, deterministic, and focused on the supported public API.

1. Choose The Audience And Scope

Decide whether the example is for:

• a first-time external user,

• a more advanced public workflow,

• or an internal exploratory or developer-only script.

Prefer putting first-use public examples in examples/airfoil/ or examples/wing/. Use public imports such as import buffalo_wings.airfoil as bwa and import buffalo_wings.wing as bww. Avoid importing from buffalo_wings.*.internal in user-facing examples.

If an example is exploratory, GUI-oriented, or primarily a developer aid, keep that purpose clear in the file name and in the docs placement.

2. Create The Example Script

Add the script under examples/ in the most specific directory that fits.

Keep the example small enough that a new user can understand it quickly. Prefer one main idea per example. Print stable, useful output when the script is run from the command line.

Stable output means:

• no timestamps,

• no random values unless explicitly seeded,

• no machine-specific paths,

• and no output that depends on unordered iteration.

Use a main() function and the standard:

if __name__ == "__main__":
    main()

pattern so the example can be executed directly.

3. Verify The Example Itself

Run the example directly:

uv run python examples/<path-to-example>.py

Run Ruff on the example or example directory:

uv run ruff check examples/<subdir>

Run the strict type checkers on the example file when it is intended to be public-facing:

uv run mypy examples/<path-to-example>.py
uv run basedpyright examples/<path-to-example>.py

4. Decide Whether The Example Belongs In The Docs

If the example is a user-facing example that should appear in the documentation, add it to the generated example-output workflow.

If the example is exploratory or internal, it does not need to appear on the main examples page.

Examples that are included in the docs should:

• use the supported public API,

• have stable command-line output,

• and remain short enough to work well with literalinclude.

5. Register The Example Output Generator

Documentation examples with expected output are listed in:

• scripts/update_example_outputs.py

Add a new ExampleOutputSpec entry that maps:

• the example script path under examples/,

• to an output file under sphinx/source/examples/generated/.

Then regenerate the outputs with:

uv run python scripts/update_example_outputs.py

These generated output files are intended to be tracked in git.

6. Add The Example To The Sphinx Examples Page

Update:

• the Sphinx examples page

For each user-facing example shown there, include:

• a short description,

• the uv run python ... command used to run it,

• a literalinclude block for the example script,

• and a literalinclude block for the generated output file.

Keep the examples page focused on the best entry points for a new user. Do not mix first-use examples with exploratory scripts unless there is a clear reason to do so.

7. Update Other User-Facing References If Needed

If the new example is a recommended entry point, update any of the following pages as appropriate:

• README.md

• the documentation home page

• release-readiness or roadmap documents that reference example paths

If a directory or file name changes, update any documentation links that refer to the old path.

8. Rebuild The Docs

Build the documentation with:

./scripts/build_docs.sh

This script will:

• regenerate the tracked example output files,

• rebuild the Sphinx documentation,

• and fail if the docs build encounters warnings treated as errors.

On Windows, use:

scripts\build_docs.bat

9. Run The Full Checks When The Change Is Substantial

For substantial documentation or example changes, run:

./scripts/run_checks.sh

The standard checks now regenerate the documented example outputs and verify that the tracked files under sphinx/source/examples/generated/ are up to date.

If that check fails, regenerate the outputs and include the updated files in the change set.

Checklist

Before finishing an example change, confirm the following:

• the example uses the intended public API,

• the example runs successfully,

• the example output is stable,

• the generated output file was refreshed if the example is shown in the docs,

• the Sphinx examples page includes the example if it is user-facing,

• and the relevant quality checks pass.