Skip to content

docs: fix terminal directives#2810

Open
jahn-junior wants to merge 2 commits into
mainfrom
work/fix-terminal-directives
Open

docs: fix terminal directives#2810
jahn-junior wants to merge 2 commits into
mainfrom
work/fix-terminal-directives

Conversation

@jahn-junior

@jahn-junior jahn-junior commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

Note that I did not assess the quality or necessity of any of these terminal directives. This PR is only a stopgap to get everything rendering correctly until I complete CHARMCRAFT-684 next pulse.


  • I've followed the contribution guidelines.
  • I've signed the CLA.
  • I've successfully run make lint && make test.
  • I've added or updated any relevant documentation.
  • In documents I changed, I added a meta description if one was missing.
  • I've updated the relevant release notes.

@jahn-junior
jahn-junior requested a review from lengau as a code owner July 23, 2026 22:52
Copilot AI review requested due to automatic review settings July 23, 2026 22:52
@jahn-junior
jahn-junior requested a review from a team as a code owner July 23, 2026 22:52
Comment on lines +111 to +117
.. terminal::

multipass shell charm-dev
...
ubuntu@charm-dev:~$ sudo snap install charmcraft --classic

.. terminal::
:user: ubuntu
:host: charm-dev

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These will get merged into a single terminal session once we bump the sphinx-terminal version.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Stopgap documentation update to make terminal examples render correctly under the sphinx_terminal Sphinx extension, primarily by converting code-block command/output pairs into .. terminal:: blocks and marking output-only snippets.

Changes:

  • Replaced several .. code-block:: bash + .. terminal:: sequences with single .. terminal:: blocks that include both command and output.
  • Added :output-only: to terminal blocks that show output without input.
  • Adjusted a few doc examples (including comment formatting in manage-channels) as part of fixing rendering issues.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
docs/howto/pack-a-hooks-based-charm-with-charmcraft.rst Converts command/output examples to .. terminal:: blocks for consistent rendering.
docs/howto/manage-web-app-charms/use-web-app-charm.rst Marks a terminal snippet as output-only to render as plain output.
docs/howto/manage-web-app-charms/configure-web-app-charm.rst Adds an output-only terminal block for expected results.
docs/howto/manage-the-current-charmhub-user.rst Converts login example to a terminal block with command + output.
docs/howto/manage-revisions.rst Uses terminal blocks for command + output and marks an output-only excerpt.
docs/howto/manage-resources.rst Consolidates upload examples into terminal blocks containing command + output.
docs/howto/manage-extensions.rst Converts several dropdown examples to terminal blocks and adds output-only metadata.
docs/howto/manage-charms.rst Updates multiple lifecycle examples in dropdowns to use terminal blocks.
docs/howto/manage-charmcraft.rst Converts macOS and Multipass examples to terminal blocks (including user/host options).
docs/howto/manage-channels.rst Marks channel table as output-only and changes how a hidden explanatory block is represented.
Comments suppressed due to low confidence (2)

docs/howto/manage-extensions.rst:62

  • This .. terminal:: is intended to be part of the preceding dropdown example, but it’s currently less-indented than the dropdown body, so it will be parsed outside the dropdown and may render incorrectly.
  .. terminal::

docs/howto/manage-extensions.rst:112

  • Within this dropdown, the .. terminal:: directive needs to be indented to the dropdown body level; otherwise it will be parsed outside the dropdown and can break the structure of the page.
  .. terminal::

Comment thread docs/howto/manage-extensions.rst Outdated
Comment thread docs/howto/manage-channels.rst Outdated
Comment thread docs/howto/manage-web-app-charms/configure-web-app-charm.rst Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants