docs: Pull tutorial code snippets from examples/ - #2544
Conversation
|
This is super cool! I didn't know Sphinx could do this. |
| ```{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. | ||
| ``` |
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.
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>
d85517a to
ea9b041
Compare
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>
ea9b041 to
5a173ed
Compare
james-garner-canonical
left a comment
james-garner-canonical
left a comment
There was a problem hiding this comment.
I haven't checked every example, but I really like this direction.
I assume that if a matching anchor isn't found, the docs build complains loudly, so this should be far less prone to drift that before.
I have one non-blocking concern that may be worth addressing at this point: the maximum line length we use in the charm code can lead to long lines that require horizontal scrolling in the docs -- previously we would have reformatted them manually in the docs to avoid this. Should we use a shorter maximum line length for the examples now that we're using them this way? Does this have implication for the profiles -- I think it would be fine if this was one of our divergences from the profiles, but maybe it would make the tutorial harder to follow, in which case maybe we just live with the horizontal scrolling ...
| :start-at: framework.observe(self.on["demo-server"] | ||
| :end-at: framework.observe(self.on["demo-server"] |
There was a problem hiding this comment.
This line is too long and requires scrolling in the docs. I wonder if we should adopt a lower line length for the example charms now that we're using them this way.
2 participants
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