Документирование команд CLI с помощью Sphinx doc

Мне нужно документировать многие команды CLI, используя Sphinx doc. Я искал повсюду расширение, которое можно было бы использовать для получения вывода, аналогичного тому, как github документирует команды CLI:

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

Есть ли какие-то расширения, которые я пропустил, которые могли бы помочь с этим? Если нет, может ли кто-нибудь указать направление для его создания?

Мне нужно, чтобы я мог документировать, например, так:

.. sourcecode:: cli

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

и иметь этот выход.

Спасибо!

Источник

2 ответа

Решение

Существует широкий спектр тем, чтобы изменить внешний вид по умолчанию, как .. code:: директивные ручки. Например:

.. code::

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

Выходы с темой по умолчанию:

default_theme

С помощью sphinx_bootstrap_theme:

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')

Наконец, в первый раз я вызвал новый класс, используя .. 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>

Пользовательские CSS

Теперь это можно улучшить с помощью пользовательской директивы.

Источник

Как упомянул @cole, "это можно улучшить с помощью пользовательской директивы" - на самом деле уже есть одна подсказка sphinx (или проверьте репозиторий github)

Вы можете установить через pip install sphinx-prompt и просто добавить 'sphinx-prompt', на ваш extensions кортеж в conf.py.

После этого вы просто используете директиву .. 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"

с дополнительной осторожностью, что $ не выбирается.

Больше примеров здесь

Вы можете увидеть это в действии на этой странице, над которой я работаю (прокрутите вниз, подсказки имеют желтоватый фон)

Источник
Другие вопросы по тегам