Show user-modifiable text in Sphinx code-block

Question

When using Sphinx to document shell command-line examples, is there a good way to show user-modifiable text? For example, what is a good way to show <file to delete> is something the user should specify and not type verbatim

Delete a File
`````````````

This is how to delete a file

.. code-block:: console

  $ rm <file to delete>

In other documentation systems, this text might be italicized, but using code-block appears to disable all (most?) inline formatting.

From what I've seen currently the prevalent style of doing this in Python is using [`argparse`](https://docs.python.org/3/library/argparse.html#module-argparse) for the implementation. `argparse` provides some automation and solves part of the normal problems out-of-the-box. Documenting command line interfaces tends to follow the style used in the official documentation. There are several sphinx extensions that facilitate writing documentation for `argparse`, I wrote this lengthy [answer on the subject](https://stackoverflow.com/a/60446946) — bad_coder, Dec 29 '20 at 20:04
If on the other hand you are trying to document a Unix shell style command, there are probably other more prevalent styles like the man pages use, etc...(It would be important to specify exactly what kind of command line interface you are documenting and what kind of style you want to follow.) — bad_coder, Dec 29 '20 at 20:06
You could use a `parsed-literal` block. It can process inline markup such as `****`. Other examples: https://stackoverflow.com/a/44528427/407651, https://stackoverflow.com/a/42161804/407651, https://stackoverflow.com/a/12644533/407651. — mzjn, Dec 29 '20 at 20:40

score 1 · Accepted Answer · answered Dec 30 '20 at 09:31

The convention is to use ALL_CAPS, replacing spaces with underscores _, for user substitutions. This convention is also used for environment variables in shell scripts.

.. code-block:: console

    $ rm FILE_TO_DELETE

Unfortunately there is no lexer that I know of that creates adequate HTML markup that one can style with custom CSS. You can try other lexers for shells than console, such as bash, but it also is suboptimal. Try the demo and view the resulting HTML markup.

Google's developer documentation style guide has excellent examples of how I think command line statements should be formatted.

With that I would suggest that you write your own lexer that does exactly what you want, if none of the available lexers are satisfactory.

Show user-modifiable text in Sphinx code-block

1 Answers1