Отображение данных словаря в документации Sphinx

У меня есть словарь в исходном коде проекта Python, который описывает значения конфигурации по умолчанию. Словарь довольно длинный. Я хотел бы видеть словарь в документации Sphinx в другом формате, кроме "View source", чтобы люди могли быстро проверить значения по умолчанию.

Предоставляет ли Sphinx опции для форматирования словарных переменных для удобного для чтения формата при использовании с Sphinx autodoc? В настоящее время я использую .. automodule:: для выгрузки всего модуля, и я получаю словарь как один длинный дамп строк в документации (без новой строки, довольно печатной, ничего), будучи в основном нечитаемым.

Предоставляет ли Sphinx инструменты для печати значений отдельных переменных исходного кода
Есть ли доступная печать?

Ответ 1

Это может быть не самое изящное решение (было бы гораздо лучше написать правильную директиву для вывода довольно печатного словаря), но это работает сейчас:

Добавьте настраиваемую директиву exec, указанную здесь здесь, в ваш файл Sphinx.conf, затем в файле .rst, который вы хотите распечатать словарь, выполните следующие действия:

.. exec::
    import json
    from some_module import some_dictionary
    json_obj = json.dumps(some_dictionary, sort_keys=True, indent=4)
    print '.. code-block:: JavaScript\n\n    %s\n\n' % json_obj

Это будет печатать ваш словарь в кодовом блоке JavaScript в ваших документах (который, как я считаю, является наилучшим способом отображения словарей в документах).

Ответ 2

Если значение словаря не вычислено и читается человеком, как это

FRUITS = {
   "Apple": "Red and Delicious",
   # note: eating too much orange make your hands orange
   "Orange": "A lot of vitamin C"
}

скажем, у вас есть вышеупомянутый dict, определенный в fruit.py, начиная со строки № 15

тогда вы можете сделать:

.. literalinclude:: ../path-to-file/fruit.py
   :language: python
   :lines: 15-
   :linenos:

и вы получите удобочитаемое значение + комментарии и т.д. прямо на документ