Open Stack

-----Original Message-----
From: Adrien Cunin <adrien at adriencunin.fr>
Reply: Adrien Cunin <adrien at adriencunin.fr>
Date: July 5, 2016 at 03:43:52
To: openstack-docs at lists.openstack.org <openstack-docs at lists.openstack.org>
Subject:  [OpenStack-docs] Better way to display shell commands

> Hi,
>
> From what I can see we usually use
>
> .. code-block:: console
>
> or
>
> .. code-block:: shell-session
>
> (which actually are the same)
>
> to show commands that are to be executed by the user such as
>
> # apt-get install foo
> # echo 1 > bar
>
> The main issue, and the reason I started looking into this, is that the
> html output doesn't make it easy to select commands (for copy/pasting
> typically) without the prompt.
>
> Turns out there is a Sphinx extension to do just this:
> https://github.com/sbrunner/sphinx-prompt
>
> With this extension, the following
>
> .. prompt:: bash #
>
> apt-get install foo
> echo 1 > bar
>
> will have the expected result.
> That is: looks similar to the previous version, but one can easily
> select commands without the prompt.
>
> Does it sound like a good idea?
>
> We'd need first to enable the Sphinx extension wherever we use Sphinx.
> Does that actually require to patch each git repository that contains
> documentation or do we have another way of doing it globally?
> Then, documentations should start using ".. prompt:: bash" instead of
> ".. code-block:: console" when appropriate - the change could be
> automated or not.

I recently started using this for Flake8 (flake8.pycqa.org) and it
seems to work very well.

+1 from me.

--
Ian Cordasco