34

Using Sphinx, I know you can show a code snippet by having something like:

.. code-block:: ruby.
  ${your ruby code goes here}

How can I show a code snippet of terminal or shell commands not related to any languages? I don't care if they are not highlighted properly syntax wise, I just want them show up in the doc as a piece of code other than normal text.

Example

$ ls -lsa . 
$ make file
mzjn
  • 48,958
  • 13
  • 128
  • 248
Shengjie
  • 12,336
  • 29
  • 98
  • 139

3 Answers3

48
.. code-block:: console

is meant for interactive sessions. Bash or sh didn't work for me.

( from http://build-me-the-docs-please.readthedocs.org/en/latest/Using_Sphinx/ShowingCodeExamplesInSphinx.html#pygments-lexers )

Marco Mariani
  • 13,556
  • 6
  • 39
  • 55
  • 2
    This is preferred over `bash` or `sh`, since it's a console/terminal that is being described, not a script. Be aware though that it doesn't handle long lines well. – Travis Spencer Jul 29 '16 at 15:27
34

For Linux console commands you could use bash or sh:

.. code-block:: bash

   $ ls -lsa .
   $ make file

Highlighting wouldn't probably work right all the time, but at least you give it a chance.

You can also set the default highlighting in the beginning of the file if you use the @Bonlenfum way with double colons:

.. highlight:: sh
Nizam Mohamed
  • 8,751
  • 24
  • 32
wswld
  • 1,218
  • 15
  • 32
  • 2
    In this case, you should prefer `console` rather than `bash`, as in Marco Mariani's answer. `bash` might misinterpret console-specific syntax such as the $ / # in the beginning of a line – tbrugere Jun 23 '21 at 13:35
24

You can indent the text you want to be written as code, and precede that with a double colon. For example:

Some body text explaining what's coming up::

    ls -lsa .
    make file

Or it also turns out you can get away without any text before, just using the double colons. In the first case, one colon gets rendered, while for this case, just the code gets rendered.

::
    mkdir test
    cd !$

Then the commands will come out in a fixed-width font, and, depending on the style sheets you've chosen, highlighted as well (by default, highlighted with green background).

You can also inline-highlight with backticks, e.g. `ls -lsa .`.

Bonlenfum
  • 19,101
  • 2
  • 53
  • 56
  • As [wswld](https://stackoverflow.com/users/1349940/wswld) [notes below](https://stackoverflow.com/a/22317799/2809027), this lightweight approach is inadvisable unless also paired with a parser directive resembling `.. highlight:: console` at the head of your ReST document. Doing so informs the ReST parser (e.g., Sphinx) of the default language to be used for all code blocks lacking an explicit language. In this case, that should be `console` – the "language" associated with Bash shell one-liners intended to be run interactively. That said, explicit is better than implicit. – Cecil Curry Jun 26 '18 at 03:42