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.

Cole · Accepted Answer · 2014-05-15 23:40:45Z

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:

default_theme

With the sphinx_bootstrap_theme:

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>

custom-css

Now this could be improved with a custom directive.

Peter Hanley · Accepted Answer · 2014-05-16 18:07:09Z

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)

This is nice, but there is no example how to write the output of commands. :(

Collectives™ on Stack Overflow

Documenting CLI commands with Sphinx doc

2 Answers 2

Comments

1 Comment

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

1 Comment

Related