Should we use the Sphinx `terminal-output` extension?

[benjamin051000]

The canonical starter pack auto-enables an extension called terminal-output:

kernel-docs/docs/conf.py

Lines 218 to 236 in 4b49500

	# NOTE: The canonical_sphinx extension is required for the starter pack.
	# It automatically enables the following extensions:
	# - custom-rst-roles
	# - myst_parser
	# - notfound.extension
	# - related-links
	# - sphinx_copybutton
	# - sphinx_design
	# - sphinx_reredirects
	# - sphinx_tabs.tabs
	# - sphinxcontrib.jquery
	# - sphinxext.opengraph
	# - terminal-output
	# - youtube-links
	extensions = [
	"canonical_sphinx",
	"sphinxcontrib.cairosvgconverter",
	]

Here's how it works (from https://github.com/canonical/canonical-sphinx-extensions?tab=readme-ov-file#terminal-output):

Single command sample:

:input: single command
:user: root
:host: vm
:dir: /tmp/dir/

output line one
output line two

Multiple command sample:

:user: root
:host: vm
:dir: /tmp/dir/

:input: a command
output line one
output line two

:input: another command
more output

The output is rendered like this (screenshot) (built in this repo):

Currently, I tend to use simple code blocks to specify terminal commands. I'm wondering if I should switch to using this instead?

It has a different aesthetic, but also clearly shows the CWD, which is helpful in tutorials when I ask the user to cd in and out of various directories. However, it appears that the extension does not have a "copy" button to easily copy the commands, which is definitely a downside.

Also, the inclusion of the command-line prompt appears to violate the Canonical Documentation Style Guide.

I could see this being beneficial in my tutorial, since I can paste the entire output of a command (apparently there is an option to make the output scrollable so it doesn't take up too much space on the page), which may help users better understand if their output matches the expected output of a command.

Should I use this terminal-output extension, normal markdown code blocks, or something else? Any advice about this would be greatly appreciated, thanks!

[benjamin051000]

Here's a screenshot of the rendered output of commands using normal markdown code blocks, as a comparison to the above (content from WIP #41):

---

To me, it feels less obvious that the code block is trying to convey it's meant to be pasted into your terminal and ran. I'm no designer, though. 🤠

[AnneCYH]

Hi @benjamin051000 , you can, definitely.

For me, deciding on code-block vs terminal-output depends on what you're trying to convey.

For terminal-output, it's best when you want to demonstrate the expected output.
As you mentioned, this would be especially helpful for tutorials.

However in that view it might be a little less obvious that you can in fact copy & paste.

This is how we tried to keep the best of both worlds in Pebble docs:
https://canonical-pebble.readthedocs-hosted.com/en/latest/tutorial/getting-started/

hope that helps!

[gagath]

I like being able to copy/paste commands.

For terminal sessions, sphinx already supports the console lexer which can parse terminal output and format it:

Not sure what this terminal extension is providing more than the built-in lexer.

[benjamin051000]

@AnneCYH thanks for the info and the example. I see how you use both in that example and that would probably work for me for the time being.

[benjamin051000]

@gagath It looks like mostly different styling... I just tried that by doing a

```console
user@host:~/path$ echo hi
hi
```

And it worked. It does include a copy button... but it copies everything, including the prompt and output. I'd love an extension of our terminal-output where you could make the copy button only copy the command... that would be ideal. You can always select other text if you need to copy it. 🤷🏼‍♂️

[benjamin051000]

Hm. And for some reason, the output is italicized... not sure why.

[benjamin051000]

It also appears to be somewhat strict about the prompt for proper styling...

[benjamin051000]

One snag with terminal-output is described here: canonical/canonical-sphinx-extensions#49