docs: use start-after/end-before for example includes

[lavaFreak]

Related Issues

• Closes Use start-after/end-before when including examples #104

What changes are proposed in this pull request?

• replace line-number-based example literalinclude directives with :start-after: / :end-before: markers
• add matching markers to the example scripts so the docs stay stable as those files evolve
• keep the existing examples and emphasis focused on the same sections, while making the includes less brittle

How is this PR tested?

• git diff --check
• manual review of the updated doc includes and inserted example markers

Summary by Sourcery

Stabilize documentation examples by marking example code regions and updating includes to reference them instead of line numbers.

Enhancements:

• Add explicit start/end marker comments around key regions in example scripts so they can be reliably referenced from the docs.

Documentation:

• Update Sphinx example includes to use :start-after: and :end-before: markers instead of line-number-based literalinclude ranges for more robust, future-proof documentation.

[sourcery-ai]

Reviewer's Guide

Replaces line-number-based Sphinx literalinclude directives with marker-based includes by adding start/end comment markers in example scripts and updating the docs to target those markers, making the examples more stable as code evolves.

Flow diagram for marker-based Sphinx literalinclude usage

flowchart LR
    Docs_sources["RST docs (index.rst, examples.rst)"] --> Literalinclude["Sphinx literalinclude directive<br/>(:start-after:, :end-before:)"]
    Literalinclude --> Example_scripts["Example scripts (ex_0..ex_7)<br/>with [start ...] / [end ...] markers"]

Loading

File-Level Changes

Change	Details	Files
Add Sphinx-compatible start/end markers around key sections in example scripts for use with literalinclude :start-after:/:end-before:.	Wrap the stage usage methods, parser definition, and parse_args implementation in the adding-arguments example with named start/end markers. Wrap the init, flaky stage body, and parser sections in the retryable stages example with named start/end markers. Wrap parser customization sections in examples that remove retry arguments or run stages by default with named start/end markers. Wrap customization hooks for stage behavior, individual stages, and summary printing in their respective examples with named start/end markers. Add an end marker for the basic example script to delimit the include region.	example/ex_0_the_basics.py example/ex_1_removing_the_retry_arguments.py example/ex_2_running_certain_stages_by_default.py example/ex_3_adding_arguments.py example/ex_4_customizing_stage_behavior.py example/ex_5_customizing_individual_stages.py example/ex_6_creating_retryable_stages.py example/ex_7_customizing_the_summary.py
Update Sphinx documentation to use marker-based literalinclude directives instead of line-number ranges.	Switch literalinclude directives in the examples documentation to use :start-after: and :end-before: options keyed to the new markers in the example scripts. Adjust any include targets in the index or examples overview pages to align with the new marker names while preserving which code regions are highlighted.	doc/source/examples.rst doc/source/index.rst

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#104	Update documentation example includes to use :start-after: and :end-before: markers instead of line-number-based ranges.	✅
#104	Insert matching start-after/end-before marker comments into the example scripts so the Sphinx literalinclude directives can target stable code regions.	✅

Possibly linked issues

• #: The PR changes literalinclude directives and example files to use start-after/end-before, matching the issue request.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (9bf2d7d) to head (fd976fa).

Additional details and impacted files

@@            Coverage Diff            @@
##            master      #297   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            2         2           
  Lines          177       177           
  Branches        15        15           
=========================================
  Hits           177       177           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[jmgate]

question: Can we use consistent start/end strings?

Is it possible to use the same start and end strings in each example file? E.g.,

# [start include-in-docs-examples]
...
# [end include-in-docs-examples]

Maybe that cleans things up a bit, in that the rst literalinclude looks the same in each case. Thoughts? 🤷‍♂️

[lavaFreak]

Thanks, Jason. I tightened this up in 2722b7e.

The single-snippet example files now all use the same marker pair:

• [start include-in-docs-examples]
• [end include-in-docs-examples]

For the two files that contribute multiple snippets (ex_3 and ex_6), I kept the same include-in-docs-examples-* prefix and added section-specific suffixes so the include targets stay unambiguous.

[jmgate]

chore: Run pre-commit run --all-files

@lavaFreak, can you see about setting up pre-commit and then running it against all files in the repo?

I'll look into the CodeFactor failures on Monday.

[lavaFreak]

I set up the local environment from the repo docs, installed the hooks, and ran pre-commit run --all-files from the repo root. That passed locally after the formatter-only follow-up in fd976fa, which is now pushed to the branch.

[lavaFreak]

I took a look at the remaining CodeFactor failures. From what I can tell, they are pointing at the pre-existing shell=True usage in the example scripts rather than the marker/doc changes introduced in this PR. The shell=True lines were already present before this branch, and this PR only adds the literalinclude markers plus the associated docs updates.

[jmgate]

I've filed #300 to deal with the CodeFactor findings. Maybe some setting changes behind the scene, such that these are causing a problem now vs before.