docs: fix incorrect indentation in YAML snippets
Metadata
Current evaluation
Merged documentation fix for incorrectly indented YAML snippets caused by sphinx_toolbox. Replaces affected code-block directives with code directives to bypass the rendering bug. Changes span four files and were approved despite minor CI failures.
Suggested action: —
No scores available.
Issue body
Some YAML snippets in the docs are rendered incorrectly, with some properties indented less than they should be. For example, in the [charmcraft.yaml doc](https://documentation.ubuntu.com/charmcraft/stable/reference/files/charmcraft-yaml-file/#containers):
<img width="875" height="880" alt="Screenshot from 2025-10-24 19-37-50" src="https://github.com/user-attachments/assets/f96928f8-71fc-45e9-baa5-379349dc9af8" />
Under `bases`, the `channel` and `architectures` properties should be indented to the same level as `name`. Similarly, under `mounts`, the `location` property should be indented to the same level as `storage`.
I've pinned the issue down to the sphinx_toolbox extension, which the Charmcraft docs use. Bug report: https://github.com/sphinx-toolbox/sphinx-toolbox/issues/198
The extension introduces a custom `code-block` directive that supports a `tab-width` option. It doesn't look like the Charmcraft docs require this custom directive. The docs presumably use the extension for a different purpose.
Workaround approaches (that I can think of):
1. Replace the offending code blocks by `literalinclude`.
2. <mark>Use `code` instead of `code-block`. The extension doesn't touch the `code` directive, it seems.</mark>
3. Reduce the level of indentation by extracting the deeply-nested YAML into standalone code blocks.
4. Don't import the whole extension; only import the modules that are needed.
5. Redefine `code-block` to the built-in directive.
After discussion (see comments) we went with approach 2. Only replacing `code-block` by `code` where the output was broken. [Preview of one of the fixed snippets](https://canonical-ubuntu-documentation-library--2475.com.readthedocs.build/charmcraft/2475/reference/files/charmcraft-yaml-file/#containers)
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.6-35b-a3b | — | — | Merged documentation fix for incorrectly indented YAML snippets caused by sphinx_toolbox. Replaces affected code-block directives with code directives to bypass the rendering bug. Changes span four files and were approved despite minor CI failures. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged fix for incorrectly indented YAML snippets caused by the sphinx_toolbox extension. Affected code-block directives were replaced with standard code directives to bypass the rendering bug. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged fix for incorrectly indented YAML snippets caused by sphinx_toolbox. Replaced affected code-block directives with code directives to bypass faulty rendering and restore proper formatting. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #466 docs: fix yaml in examples | craft-parts | merged | Merged a documentation fix correcting YAML syntax in example parts.yaml by replacing underscores with hyphens. Approved by reviewer, passed CI, and changed two lines in one file. | |
| #5849 docs: fix YAML reference types | snapcraft | merged | Merged documentation fix correcting YAML reference types. Approved by two reviewers, passed all CI checks, and updated one file with six additions and two deletions. | |
| #919 docs: fix indentation | craft-application | merged | Merged documentation fix correcting an indentation error introduced in a prior review. Approved by two reviewers, passed all CI checks, and applied a minimal two-line change. | |
| #433 fix: provide more info in YAML errors | craft-application | merged | Merged to fix disappearing YAML error information, resolving issue #427. Approved by two reviewers, passed CI checks, and modified three files (+27/-2 lines) to restore detailed error reporting. | |
| #325 docs: use canonical-sphinx | craft-application | merged | Merged documentation update to adopt canonical-sphinx and remove unused extensions. Approved by two reviewers, passed CI, and modified four files (+30/-83 lines). | |
| #23 docs: use canonical-sphinx | craft-grammar | merged | Merged after two approvals and passing CI. Updates documentation to use canonical-sphinx, modifying 7 files with a net reduction of 72 lines. |