Documenting CLI commands with Sphinx doc

Question

I need to document many CLI commands using Sphinx doc. I have searched everywhere for an extension that could be used to produce an output similar to how github documents CLI commands:

https://developer.github.com/v3/#parameters

Is there any extension that I missed that could help with that? If not, can anyone point the direction to building one?

I need to be able to document for example like this:

.. sourcecode:: cli

  $ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed"

and have that output.

Answer 1

There is a wide range of themes to change the default look of how the .. code:: directive handles. For instance:

.. code::

   $ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed"

Outputs with the default theme:

With the sphinx_bootstrap_theme:

However, if you wanted to create a closer feel to the github documents you can extend the default css and use the .. raw:: directive to call a custom class. I created a _static/cli.css file in my docs directory with the following:

.cli {
  border: 1px solid #cacaca;
  font: 12px/1.4em Consolas, 'Liberation Mono', Courier, monospace;
  padding: 10px;
  overflow:auto;
  border-radius: 3px;
  margin: 2em 0;
  background-color: #444;
  color: #fff;
  position: relative;
} 

Then added the following to the conf.py. There are other ways to extend the CSS, but this is just the one I choose at the time.

html_static_path = ['_static']
def setup(app):
   app.add_stylesheet('cli.css')

Finally in the rst I called the new class using the .. raw:: directive.

.. raw:: html

   <div class='cli'>
   $ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed" <br>
   $ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed" <br>
   $ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed" <br>
   $ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed" <br>
   </div>

Now this could be improved with a custom directive.

Answer 2

As @cole mentioned, "this could be improved with a custom directive" - there actually is one already sphinx-prompt (or check the github repo)

You can install via pip install sphinx-prompt and just add 'sphinx-prompt', to your extensions tuple in conf.py.

After that, you just use the directive .. prompt:: bash with the command underneath like

.. prompt:: bash

    curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed"

and it will output as

$ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed"

with the additional nicety that the $ is not selectable.

---

More examples here

You can see it in action on this page that I'm working on (scroll down, the prompts are yellowish in background)