docs: Pull tutorial code snippets from examples/#2544
Draft
tonyandrewmeyer wants to merge 2 commits into
Draft
Conversation
Replace hardcoded code fences in the tutorial pages with Sphinx literalinclude directives that pull from the matching example charms in examples/. This keeps the tutorial automatically in sync with the canonical source, and removes ~750 lines of duplicated code. Strategy per snippet type: - Full method or class: :pyobject: Class.method - Single line or small fragment: :start-at:/:end-at: patterns on the line content (no marker comments needed in sources) - Multi-line block: :start-at:/:end-before: patterns anchored on the next section - Full file (skipping copyright header): :start-at: with the first real line Intermediate states that don't exist in examples/ (e.g. the empty starting charm class, lines shown only to be removed, contrastive "don't do this" snippets, and a troubleshooting timeout hint) are left inline. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Contributor
|
This is super cool! I didn't know Sphinx could do this. |
Comment on lines
+57
to
61
| ```{literalinclude} ../../../examples/k8s-1-minimal/charmcraft.yaml | ||
| :language: yaml | ||
| :start-at: 'title: Web Server Demo' | ||
| :end-at: how to write a Kubernetes charm with Ops. | ||
| ``` |
Contributor
There was a problem hiding this comment.
We could use start-after and end-after with comment anchors in cases where we worry that this won't be robust. Thinking about this case specifically, I guess Sphinx would yell at us if we changed the end line of the description so there was no match, so this seems great as-is.
tonyandrewmeyer
added a commit
to tonyandrewmeyer/operator
that referenced
this pull request
Jun 8, 2026
Per review feedback, exclude docs/tutorial/ from ruff entirely (the tutorial will be migrated to literalinclude separately in canonical#2544) and drop the second 'quote-style = preserve' ruff format pass. The remaining docs now use single quotes consistently with the rest of the project. Also add docs/ruff.toml with line-length = 80 so code snippets in the docs wrap at a width that doesn't require horizontal scrolling when rendered. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
NOT FOR MERGING OR REVIEW! I have not done verification of side-by-side doc generation. PR opened for discussion.
Replace hardcoded code fences in the tutorial pages with Sphinx
literalincludedirectives that pull from the matching example charms inexamples/. This keeps the tutorial automatically in sync with the canonical source, and removes ~750 lines of duplicated code.Strategy per snippet type:
:pyobject: Class.method:start-at:/:end-at:patterns on the line content (no marker comments needed in sources):start-at:/:end-before:patterns anchored on the next section:start-at:with the first real lineIntermediate states that don't exist in
examples/(for example, the empty starting charm class, lines shown only to be removed, contrastive "don't do this" snippets, and a troubleshooting timeout hint) are left inline.Preview