使用Sphinx doc记录CLI命令

Question

我需要使用Sphinx doc记录许多CLI命令。我到处搜索了一个扩展，可用于生成类似于github文档CLI命令的输出：

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

我错过了任何可以帮助的扩展吗？如果没有，任何人都可以指出建立一个方向吗？

我需要能够以这样的方式记录：

.. sourcecode:: cli

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

并有输出。

谢谢！

Answer 1

有很多themes可以更改.. code::指令处理的默认外观。例如：

.. code::

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

使用默认主题输出：

使用sphinx_bootstrap_theme：

但是，如果您想要更好地了解github文档，可以扩展默认的css并使用.. raw::指令来调用自定义类。我在docs目录中创建了一个_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')

最后，我在第一次使用.. 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>

现在可以使用自定义指令进行改进。

Answer 2

正如@cole所提到的，＆＃34;这可以通过自定义指令来改善＆＃34; - 实际上已有一个sphinx-prompt（或检查github repo）

您可以通过pip install sphinx-prompt安装，只需将'sphinx-prompt',添加到conf.py中的extensions元组。

之后，您只需使用指令.. 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"

具有额外的精确性，$是不可选择的。

---

More examples here

你可以看到它在行动中on this page that I'm working on（向下滚动，背景中的提示是黄色的）