How format doc within :param <name>: in reStructuredText markup?

I am trying to document certain :param and want to give examples like

    :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.

My main problem are line breaks or paragraphs. As us see i already added |, \n All is ignored. If i add a new line everything after is just not rendered.

For rendering i use IntelliJ set to reStructuredText. I even tried to intend by 3 spaces as documentation tells.

So is there a way to apply formatting within :param or similar parts?

I also tried to put the Example within the normal doc (above) ":param"s but it is also not correctly rendered (tried ::, .. code-block:: python). can someone please provide an example how to put such a list of tuple or general code into pydoc with reStructuredtext. Probably intellj renderer has a bug?

Solution

In rST, the :some thing: syntax starts a field-list. :some thing: is the "field name" and the content may consist of one or more body elements (paragraph, lists, code block, ...), all indented relative to the field-list marker and separated by a blank line.

The following examples are tested with plain Docutils (rst2html5). Additional constraints and problems may be added by "IntelliJ".

Minimal changes:

Use a literal newline instead of \n.
At least a single space is required after a line-block marker.
An empty line is required after any block-level element (here, the line-block).

: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.

With literal-block:

    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.

With a "code" block:

: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.

Rendering in firefox