Как отформатировать документ внутри :param <name>: в разметке reStructuredText?
Я пытаюсь задокументировать определенные :param и хочу привести такие примеры, как
:param mapper_matrix:
lookup table with columns ref_col, ref_col_2 and value.\n
|**Example:**
| [("s1", "p1", "state1"),
| ("s1", "p2", special),
| ("s2", "p1", "state3"),
| ("s2", "p2", "state4")]
Every missing mapping will result in a null value in the new column.
Моя основная проблема — разрывы строк или абзацы. Как мы видим, я уже добавил |, \n
Все игнорируется. Если я добавлю новую строку, все после нее просто не будет отображаться.
Для рендеринга я использую IntelliJ, установленный в reStructuredText. Я даже пытался указать на 3 пробела, как сказано в документации.
Итак, есть ли способ применить форматирование внутри :param или подобных частей?
Я также пытался поместить пример в обычный документ (выше) ":param", но он также отображается неправильно (пробовал ::, .. code-block:: python). может кто-нибудь привести пример того, как поместить такой список кортежей или общего кода в pydoc с помощью reStructuredtext. Вероятно, в рендерере intellj есть ошибка?
Ответы 1
В rST синтаксис :some thing: запускает список полей .
:some thing: — это «имя поля», а содержимое может состоять из одного или нескольких элементов тела (абзац, списки, блок кода, ...), все с отступом относительно маркера списка полей и разделены пустой строкой.
Следующие примеры протестированы с использованием простых Docutils (rst2html5). Дополнительные ограничения и проблемы могут быть добавлены IntelliJ.
Минимальные изменения:
- Используйте буквальную новую строку вместо
\n. - После маркера блока строки должен быть хотя бы один пробел.
- После любого элемента уровня блока (здесь — блока строки) требуется пустая строка.
:param mapper_matrix:
lookup table with columns ref_col, ref_col_2 and value.
| **Example:**
| [("s1", "p1", "state1"),
| ("s1", "p2", special),
| ("s2", "p1", "state3"),
| ("s2", "p2", "state4")]
Every missing mapping will result in a null value in the new column.
С литеральным блоком:
lookup table with columns ref_col, ref_col_2 and value.
Example::
[("s1", "p1", "state1"),
("s1", "p2", special),
("s2", "p1", "state3"),
("s2", "p2", "state4")]
Every missing mapping will result in a null value in the new column.
С блоком «код»:
:param mapper_matrix:
lookup table with columns `ref_col`, `ref_col_2` and `value`.
Example:
.. code:: python
[("s1", "p1", "state1"),
("s1", "p2", special),
("s2", "p1", "state3"),
("s2", "p2", "state4")]
Every missing mapping will result in a null value in the new column.
Рендеринг в Firefox
спасибо за этот хороший ответ, можете ли вы добавить скриншот того, как это отображается с помощью «rst2html5»
нет, я хотел бы иметь что-то, что работает независимо от ide