CODEWITHSUNDEEP
pythoncommand-line-interfacepython-sphinx
Edy Bourne
Edy Bourne

Reputation: 6187

Documenting CLI commands with Sphinx doc

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.

Upvotes: 2

Views: 2999

Answers (2)

Peter Hanley
Peter Hanley

Reputation: 1284

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)

Upvotes: 2

Cole
Cole

Reputation: 1769

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.

Upvotes: 3

Related Questions