Example Workflow

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

Goal

Examples in Buffalo Core should demonstrate the intended public API with the smallest practical script. Examples shown in the documentation should also produce stable command-line output that can be tracked in git and included in Sphinx.

1. Choose The Example Scope

Decide whether the example is:

  • a first-use public example,

  • a more advanced public example,

  • or a developer-only exploratory script.

Prefer putting public examples directly under examples/ because Buffalo Core currently has a small, flat example surface. Use public imports such as from buffalo_core.numeric import as_float_array. Avoid private, internal, or project-template imports in user-facing examples.

2. Create The Example Script

Add the script under examples/. Keep the script short and focused on one main idea. Prefer deterministic printed output over interactive behavior.

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 direct-execution pattern.

3. Verify The Example

Run the example directly:

uv run python examples/<example-name>.py

Run Ruff on the example or examples directory:

uv run ruff check examples

If the example is intended to be a documented public example, also run the type checkers on it:

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

4. Decide Whether The Example Belongs In The Docs

If the example is a recommended public entry point, include it on the Sphinx examples page. If it is primarily exploratory or developer-only, it does not need to appear there.

Examples included in the docs should:

  • use the supported public API,

  • have stable output,

  • and remain short enough to work well with literalinclude.

5. Add The Example To The Sphinx Examples Page

Update the Sphinx examples page:

For each documented example, include:

  • a short description,

  • the uv run python ... command,

  • a literalinclude block for the example script,

  • and a literalinclude block for the generated output file under sphinx/source/examples/generated/.

6. Refresh The Tracked Output

Run the example and copy its stable output into the matching tracked file under:

  • sphinx/source/examples/generated/

Buffalo Core does not currently maintain a separate example-output generation script. Refresh the tracked output files directly when an example changes.

7. Update Other User-Facing References If Needed

If the example is a recommended starting point, update any of the following as needed:

  • README.md,

  • the documentation home page,

  • and development documents that reference example paths.

If an example path changes, update any links that refer to the old path in the same change.

8. Rebuild The Docs

Build the documentation with:

./scripts/build_docs.sh

This verifies that the examples page includes the expected files and that the docs render cleanly.

9. Run The Full Checks When The Change Is Substantial

For substantial example or docs changes, run:

./scripts/run_checks.sh

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 tracked output file was updated if the example is shown in the docs,

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

  • and the relevant checks pass.