用Sphinx文档记录CLI命令

Question

我需要用Sphinx文档工具来记录很多命令行（CLI）指令。我到处找扩展，想要一个能生成类似于GitHub上文档的输出效果：

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

有没有我错过的扩展可以帮我实现这个？如果没有，谁能告诉我怎么自己做一个？

我希望能像这样记录：

.. sourcecode:: cli

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

然后得到这样的输出。

Answer 1

正如@cole提到的，“这可以通过自定义指令来改进”——其实已经有一个现成的指令了，叫做 sphinx-prompt（你也可以查看一下 这个GitHub库）

你可以通过 pip install sphinx-prompt 来安装它，然后在你的 conf.py 文件中的 extensions 列表里加上 'sphinx-prompt',。

安装完成后，你只需要使用指令 .. prompt:: bash，然后在下面写上命令，比如：

.. prompt:: bash

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

这样就会输出成：

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

而且还有一个小好处，就是$符号是不能被选中的。

---

这里有更多示例

你可以在我正在制作的 这个页面上看到它的实际效果（往下滚动，提示框的背景是淡黄色的）

Answer 2

有很多种主题可以改变默认的样式，让.. code::指令的显示效果更好。例如：

.. code::

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

这是使用默认主题的输出效果：

而使用sphinx_bootstrap_theme主题时的效果：

不过，如果你想让文档的样式更接近GitHub的风格，可以在默认的CSS基础上进行扩展，并使用.. raw::指令来调用自定义的样式类。我在我的文档目录下创建了一个_static/cli.css文件，内容如下：

.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;
} 

然后我在conf.py文件中添加了以下内容。虽然还有其他方法可以扩展CSS，但这是我当时选择的方式。

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

最后，在rst文件中我使用.. raw::指令调用了这个新样式类。

.. 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>

现在，这个效果还可以通过自定义指令进一步改进。