Как программно сгенерировать документацию из словаря Python и вставить ее в .rst-файл с помощью Sphinx
Я пишу инструмент настройки, который автоматизирует развертывание некоторых панелей мониторинга. Каждая панель мониторинга имеет письменное описание, доступное в инструменте, и его можно найти на развернутой панели мониторинга. Но у нас также есть некоторая функциональная документация, которая повторяет это описание, чтобы конечные пользователи могли прочитать ее вне кода. Итак, в основном мы имеем следующее:
- описание_mapping.py
dashboard_description_mapping = {"dashboard_1": "This dashboard achieves xyz"}
- README.rst
Templates
=========
Descriptions
------------
* **dashboard_1**
This dashboard achieves xyz
Я упростил подход, в реальном случае у нас есть множество дашбордов и описаний, которые все дублируются в файлеdescription_mapping.py и в README.rst.
Я хотел бы иметь возможность выполнять какую-то команду, которая дает мне следующее:
Templates
=========
Descriptions
------------
* **dashboard_1**
.. magic_command: description_mapping.dashboard_description_mapping.get("dashboard_1")
Тогда это будет отображаться так, как будто описание автоматически захватывается, и, по сути, тогда я больше не нарушаю принцип DRY.
Это возможно? Я искал некоторое время и наткнулся на этот предыдущий вопрос, но, похоже, это не дает того, что мне нужно:
- Как использовать Python для программного создания части документации Sphinx?
- Отображение словарных данных в документации Sphinx
Я хотел бы получить строку, а не просто распечатать весь словарь.
Я пытался использовать существующие функции ..autodoc, но это не дало желаемого результата, а просто распечатал словарь.
Я думал, что мой пример вполне ясен, но по сути я хочу прочитать содержимое словаря, иметь возможность извлекать строки из этого словаря и помещать их в документацию. Это означает, что любое изменение словаря приведет к изменению документации.
Так какая часть autodoc этого не сделала?
Например, я пытался использовать .. autodata, но это не распечатывало так, как я хочу. Я хочу иметь возможность напрямую обращаться к значениям в словаре сопоставления, чтобы иметь возможность распечатать их там, где захочу. А не просто распечатать весь словарь в уродливом формате.
Ответы 1
Я действительно понял, как это сделать, я использовал пользовательскую директиву ..exec из: https://stackoverflow.com/a/10146415/8580574 и просто напечатал то, как я хотел:
.. exec::
from title_desc_mappings import dashboard_description_mapping
for key, value in dashboard_description_mapping.items():
if key.startswith('dashboard'):
print(f"* **{key}**\n\n")
if value == '':
print(" No description available.\n")
else:
print(f" {value}\n")
надеюсь, это поможет кому-то еще
Пожалуйста, объясните, что в autodoc не удовлетворило ваши требования. Кроме того, можете ли вы более подробно описать ваши требования?