Существует директива replace, которая работает как `include` в Sphinx или RST? - PullRequest
Новая
       11

Существует директива replace, которая работает как `include` в Sphinx или RST?

0 голосов
/ 04 июля 2019

Я создаю пользовательскую документацию, используя Sphinx с расширением Jinja и JSON, чтобы иметь гибкий шаблон.

Решения работают довольно хорошо, но некоторые команды нуждаются в небольшом дополнительном объяснении, и для этого я нашел способпоместить этот дополнительный текст в другой файл и добавить его в документацию команды с помощью директивы include, например:

Мой первый файл с шаблоном. 

{% for cmd in commands %}
Here the command {{ cmd.description }}
{% if cmd.extra is defined %}
{% for line in cmd.extra %}
{{line}}
{% endfor %}
{% endif %}
{% endfor %}

Файл JSON дляэто решение 

{
    commands: [
        {
            "description": "Short description here"
            "extra": [".. include:: command_extra.rst"]
        }
    ]
}

Недостатком этого решения является то, что мне нужно иметь дополнительный файл rst в моем дереве для каждой команды, содержащей эту дополнительную информацию, ведьма генерирует много предупреждений и делает источникболее сложным в управлении.

Решение, которое я ожидаю найти, выглядит примерно так:

Желаемый RST-файл: 

{% for cmd in commands %}
Here the command {{ cmd.description }}
{% if cmd.extra is defined %}
{% for line in cmd.extra %}
{{line}}
{% endfor %}
{% endif %}
{% endfor %}

.. |command1_extra| replace::

     Multi line text here

.. |command2_extra| replace::

     Multi line text here

Требуемый JSON-файл: 

{
    commands: [
        {
            "description": "Short description here"
            "extra": ["|command1_extra|"]
        }
    ]
}

Существует ли какая-либо директива или расширение sphinx / rst, которая могла бы сделать возможным решение?

...