From 86bf84d6f70295ef0a08f876608e77db91766a98 Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Mon, 6 Dec 2021 05:01:28 +0100
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20NEW:=20Add=20`fieldlist`=20extensio?=
 =?UTF-8?q?n=20(#455)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Field lists are mappings from field names to field bodies, based on the
[reStructureText syntax](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists).

A prominent use case of field lists is for use in API docstrings,
as used in [Sphinx's docstring renderers](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-python-domain).
This should hopefully pave the way for use with `sphinx.ext.autodoc`
---
 .pre-commit-config.yaml                       |   4 +-
 docs/conf.py                                  |   1 +
 docs/sphinx/reference.md                      |   3 +-
 docs/syntax/optional.md                       |  91 ++++++++++++
 myst_parser/docutils_renderer.py              |  36 +++++
 myst_parser/main.py                           |   4 +
 myst_parser/mocking.py                        |   3 +-
 .../test_sphinx/sourcedirs/fieldlist/conf.py  |   4 +
 .../test_sphinx/sourcedirs/fieldlist/index.md |  19 +++
 tests/test_sphinx/test_sphinx_builds.py       |  35 +++++
 .../test_fieldlist_extension.sphinx3.html     | 131 ++++++++++++++++++
 .../test_fieldlist_extension.sphinx3.xml      |  82 +++++++++++
 .../test_fieldlist_extension.sphinx4.html     | 131 ++++++++++++++++++
 .../test_fieldlist_extension.sphinx4.xml      |  82 +++++++++++
 14 files changed, 622 insertions(+), 4 deletions(-)
 create mode 100644 tests/test_sphinx/sourcedirs/fieldlist/conf.py
 create mode 100644 tests/test_sphinx/sourcedirs/fieldlist/index.md
 create mode 100644 tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx3.html
 create mode 100644 tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx3.xml
 create mode 100644 tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx4.html
 create mode 100644 tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx4.xml

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 95936c6f..2520341e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -52,8 +52,8 @@ repos:
       args: [--config-file=setup.cfg]
       additional_dependencies:
       - sphinx~=3.3
-      - markdown-it-py>=1.0.0,<2.0.0
-      - mdit-py-plugins~=0.2.8
+      - markdown-it-py>=1.0.0,<3.0.0
+      - mdit-py-plugins~=0.3.0
       files: >
         (?x)^(
             myst_parser/.*py|
diff --git a/docs/conf.py b/docs/conf.py
index cd3f4bc6..8d1da277 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -75,6 +75,7 @@
     "dollarmath",
     "amsmath",
     "deflist",
+    "fieldlist",
     "html_admonition",
     "html_image",
     "colon_fence",
diff --git a/docs/sphinx/reference.md b/docs/sphinx/reference.md
index 1d80b99a..d87ba47f 100644
--- a/docs/sphinx/reference.md
+++ b/docs/sphinx/reference.md
@@ -47,9 +47,10 @@ List of extensions:
 
 - "amsmath": enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations
 - "colon_fence": Enable code fences using `:::` delimiters, [see here](syntax/colon_fence) for details
-- "deflist"
+- "deflist": Enable definition lists, [see here](syntax/definition-lists) for details
 - "dollarmath": Enable parsing of dollar `$` and `$$` encapsulated math
 - "html_admonition": Convert `<div class="admonition">` elements to sphinx admonition nodes, see the [HTML admonition syntax](syntax/html-admonition) for details
+- "fieldlist": Enable field lists, [see here](syntax/fieldlists) for details
 - "html_image": Convert HTML `<img>` elements to sphinx image nodes, see the [image syntax](syntax/images) for details
 - "linkify": automatically identify "bare" web URLs and add hyperlinks
 - "replacements": automatically convert some common typographic texts
diff --git a/docs/syntax/optional.md b/docs/syntax/optional.md
index bdbebaa6..5efaa762 100644
--- a/docs/syntax/optional.md
+++ b/docs/syntax/optional.md
@@ -30,6 +30,7 @@ myst_enable_extensions = [
     "colon_fence",
     "deflist",
     "dollarmath",
+    "fieldlist",
     "html_admonition",
     "html_image",
     "linkify",
@@ -589,6 +590,96 @@ and are applied to markdown list items starting with `[ ]` or `[x]`:
 - [ ] An item that needs doing
 - [x] An item that is complete
 
+(syntax/fieldlists)=
+## Field Lists
+
+Field lists are mappings from field names to field bodies,
+based on the [reStructureText syntax](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists).
+
+````md
+:name only:
+:name: body
+:*Nested syntax*: Both name and body may contain **nested syntax**.
+:Paragraphs: Since the field marker may be quite long, the second
+   and subsequent lines of a paragraph do not have to line up
+   with the first line.
+:Alignment 1: If the field body starts on the first line...
+
+              Then the entire field body must be indented the same.
+:Alignment 2:
+  If the field body starts on a subsequent line...
+
+  Then the indentation is always two spaces.
+:Blocks:
+
+  As well as paragraphs, any block syntaxes may be used in a field body:
+
+  - Me
+  - Myself
+  - I
+
+  ```python
+  print("Hello, world!")
+  ```
+````
+
+:name only:
+:name: body
+:*Nested syntax*: Both name and body may contain **nested syntax**.
+:Paragraphs: Since the field marker may be quite long, the second
+   and subsequent lines of a paragraph do not have to line up
+   with the first line.
+:Alignment 1: If the field body starts on the first line...
+
+              Then the entire field body must be indented the same.
+:Alignment 2:
+  If the field body starts on a subsequent line...
+
+  Then the indentation is always two spaces.
+:Blocks:
+
+  As well as paragraphs, any block syntaxes may be used in a field body:
+
+  - Me
+  - Myself
+  - I
+
+  ```python
+  print("Hello, world!")
+  ```
+
+A prominent use case of field lists is for use in API docstrings, as used in [Sphinx's docstring renderers](sphinx:python-domain):
+
+````md
+```{py:function} send_message(sender, priority)
+
+Send a message to a recipient
+
+:param str sender: The person sending the message
+:param priority: The priority of the message, can be a number 1-5
+:type priority: int
+:return: the message id
+:rtype: int
+:raises ValueError: if the message_body exceeds 160 characters
+```
+````
+
+```{py:function} send_message(sender, priority)
+
+Send a message to a recipient
+
+:param str sender: The person sending the message
+:param priority: The priority of the message, can be a number 1-5
+:type priority: int
+:return: the message id
+:rtype: int
+:raises ValueError: if the message_body exceeds 160 characters
+```
+
+:::{note}
+Currently `sphinx.ext.autodoc` does not support MyST, see [](howto/autodoc).
+:::
+
 (syntax/images)=
 
 ## Images
diff --git a/myst_parser/docutils_renderer.py b/myst_parser/docutils_renderer.py
index 76c6617c..d0dc4b2c 100644
--- a/myst_parser/docutils_renderer.py
+++ b/myst_parser/docutils_renderer.py
@@ -942,6 +942,42 @@ def render_dl(self, token: SyntaxTreeNode) -> None:
                     )
                     self.current_node += [error_msg]
 
+    def render_field_list(self, token: SyntaxTreeNode) -> None:
+        """Render a field list."""
+        field_list = nodes.field_list(classes=["myst"])
+        self.add_line_and_source_path(field_list, token)
+        with self.current_node_context(field_list, append=True):
+            # raise ValueError(token.pretty(show_text=True))
+            children = (token.children or [])[:]
+            while children:
+                child = children.pop(0)
+                if not child.type == "fieldlist_name":
+                    error_msg = self.reporter.error(
+                        (
+                            "Expected a fieldlist_name as a child of a field_list"
+                            f", but found a: {child.type}"
+                        ),
+                        # nodes.literal_block(content, content),
+                        line=token_line(child),
+                    )
+                    self.current_node += [error_msg]
+                    break
+                field = nodes.field()
+                self.add_line_and_source_path(field, child)
+                field_list += field
+                field_name = nodes.field_name()
+                self.add_line_and_source_path(field_name, child)
+                field += field_name
+                with self.current_node_context(field_name):
+                    self.render_children(child)
+                field_body = nodes.field_body()
+                self.add_line_and_source_path(field_name, child)
+                field += field_body
+                if children and children[0].type == "fieldlist_body":
+                    child = children.pop(0)
+                    with self.current_node_context(field_body):
+                        self.render_children(child)
+
     def render_directive(self, token: SyntaxTreeNode) -> None:
         """Render special fenced code blocks as directives."""
         first_line = token.info.split(maxsplit=1)
diff --git a/myst_parser/main.py b/myst_parser/main.py
index 07376cf8..be5d5991 100644
--- a/myst_parser/main.py
+++ b/myst_parser/main.py
@@ -16,6 +16,7 @@
 from mdit_py_plugins.colon_fence import colon_fence_plugin
 from mdit_py_plugins.deflist import deflist_plugin
 from mdit_py_plugins.dollarmath import dollarmath_plugin
+from mdit_py_plugins.field_list import fieldlist_plugin
 from mdit_py_plugins.footnote import footnote_plugin
 from mdit_py_plugins.front_matter import front_matter_plugin
 from mdit_py_plugins.myst_blocks import myst_block_plugin
@@ -61,6 +62,7 @@ def check_extensions(self, attribute, value):
                 "dollarmath",
                 "amsmath",
                 "deflist",
+                "fieldlist",
                 "html_admonition",
                 "html_image",
                 "colon_fence",
@@ -193,6 +195,8 @@ def default_parser(config: MdParserConfig) -> MarkdownIt:
         md.use(amsmath_plugin)
     if "deflist" in config.enable_extensions:
         md.use(deflist_plugin)
+    if "fieldlist" in config.enable_extensions:
+        md.use(fieldlist_plugin)
     if "tasklist" in config.enable_extensions:
         md.use(tasklists_plugin)
     if "substitution" in config.enable_extensions:
diff --git a/myst_parser/mocking.py b/myst_parser/mocking.py
index ff9d4c35..7812de94 100644
--- a/myst_parser/mocking.py
+++ b/myst_parser/mocking.py
@@ -87,6 +87,7 @@ def __init__(
         self.document = renderer.document
         self.reporter = renderer.document.reporter
         self.state_machine = state_machine
+        self.inliner = MockInliner(renderer, lineno)
 
         class Struct:
             document = self.document
@@ -95,7 +96,7 @@ class Struct:
             title_styles: List[str] = []
             section_level = max(renderer._level_to_elem)
             section_bubble_up_kludge = False
-            inliner = MockInliner(renderer, lineno)
+            inliner = self.inliner
 
         self.memo = Struct
 
diff --git a/tests/test_sphinx/sourcedirs/fieldlist/conf.py b/tests/test_sphinx/sourcedirs/fieldlist/conf.py
new file mode 100644
index 00000000..1e3d9921
--- /dev/null
+++ b/tests/test_sphinx/sourcedirs/fieldlist/conf.py
@@ -0,0 +1,4 @@
+extensions = ["myst_parser"]
+exclude_patterns = ["_build"]
+
+myst_enable_extensions = ["fieldlist"]
diff --git a/tests/test_sphinx/sourcedirs/fieldlist/index.md b/tests/test_sphinx/sourcedirs/fieldlist/index.md
new file mode 100644
index 00000000..2ed48561
--- /dev/null
+++ b/tests/test_sphinx/sourcedirs/fieldlist/index.md
@@ -0,0 +1,19 @@
+:orphan:
+
+# Test
+
+:field:
+
+:*field*: content
+
+```{py:function} send_message(sender, priority)
+
+Send a message to a recipient
+
+:param str sender: The person sending the message
+:param priority: The priority of the message, can be a number 1-5
+:type priority: int
+:return: the message id
+:rtype: int
+:raises ValueError: if the message_body exceeds 160 characters
+```
diff --git a/tests/test_sphinx/test_sphinx_builds.py b/tests/test_sphinx/test_sphinx_builds.py
index 3470487c..f0c5ebbd 100644
--- a/tests/test_sphinx/test_sphinx_builds.py
+++ b/tests/test_sphinx/test_sphinx_builds.py
@@ -399,3 +399,38 @@ def test_mathjax_warning(
         "overridden by myst-parser: 'other' -> 'tex2jax_process|mathjax_process|math|output_area'"
         in warnings
     )
+
+
+@pytest.mark.sphinx(
+    buildername="html",
+    srcdir=os.path.join(SOURCE_DIR, "fieldlist"),
+    freshenv=True,
+)
+def test_fieldlist_extension(
+    app,
+    status,
+    warning,
+    get_sphinx_app_doctree,
+    get_sphinx_app_output,
+    remove_sphinx_builds,
+):
+    """test setting addition configuration values."""
+    app.build()
+    assert "build succeeded" in status.getvalue()  # Build succeeded
+    warnings = warning.getvalue().strip()
+    assert warnings == ""
+
+    try:
+        get_sphinx_app_doctree(
+            app,
+            docname="index",
+            regress=True,
+            regress_ext=f".sphinx{sphinx.version_info[0]}.xml",
+        )
+    finally:
+        get_sphinx_app_output(
+            app,
+            filename="index.html",
+            regress_html=True,
+            regress_ext=f".sphinx{sphinx.version_info[0]}.html",
+        )
diff --git a/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx3.html b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx3.html
new file mode 100644
index 00000000..44f950a7
--- /dev/null
+++ b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx3.html
@@ -0,0 +1,131 @@
+<div class="documentwrapper">
+ <div class="bodywrapper">
+  <div class="body" role="main">
+   <div class="tex2jax_ignore mathjax_ignore section" id="test">
+    <h1>
+     Test
+     <a class="headerlink" href="#test" title="Permalink to this headline">
+      ¶
+     </a>
+    </h1>
+    <dl class="myst field-list simple">
+     <dt class="field-odd">
+      field
+     </dt>
+     <dd class="field-odd">
+      <p>
+      </p>
+     </dd>
+     <dt class="field-even">
+      <em>
+       field
+      </em>
+     </dt>
+     <dd class="field-even">
+      <p>
+       content
+      </p>
+     </dd>
+    </dl>
+    <dl class="py function">
+     <dt id="send_message">
+      <code class="sig-name descname">
+       <span class="pre">
+        send_message
+       </span>
+      </code>
+      <span class="sig-paren">
+       (
+      </span>
+      <em class="sig-param">
+       <span class="n">
+        <span class="pre">
+         sender
+        </span>
+       </span>
+      </em>
+      ,
+      <em class="sig-param">
+       <span class="n">
+        <span class="pre">
+         priority
+        </span>
+       </span>
+      </em>
+      <span class="sig-paren">
+       )
+      </span>
+      <a class="headerlink" href="#send_message" title="Permalink to this definition">
+       ¶
+      </a>
+     </dt>
+     <dd>
+      <p>
+       Send a message to a recipient
+      </p>
+      <dl class="myst field-list simple">
+       <dt class="field-odd">
+        Parameters
+       </dt>
+       <dd class="field-odd">
+        <ul class="simple">
+         <li>
+          <p>
+           <strong>
+            sender
+           </strong>
+           (
+           <em>
+            str
+           </em>
+           ) – The person sending the message
+          </p>
+         </li>
+         <li>
+          <p>
+           <strong>
+            priority
+           </strong>
+           (
+           <em>
+            int
+           </em>
+           ) – The priority of the message, can be a number 1-5
+          </p>
+         </li>
+        </ul>
+       </dd>
+       <dt class="field-even">
+        Returns
+       </dt>
+       <dd class="field-even">
+        <p>
+         the message id
+        </p>
+       </dd>
+       <dt class="field-odd">
+        Return type
+       </dt>
+       <dd class="field-odd">
+        <p>
+         int
+        </p>
+       </dd>
+       <dt class="field-even">
+        Raises
+       </dt>
+       <dd class="field-even">
+        <p>
+         <strong>
+          ValueError
+         </strong>
+         – if the message_body exceeds 160 characters
+        </p>
+       </dd>
+      </dl>
+     </dd>
+    </dl>
+   </div>
+  </div>
+ </div>
+</div>
diff --git a/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx3.xml b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx3.xml
new file mode 100644
index 00000000..58606693
--- /dev/null
+++ b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx3.xml
@@ -0,0 +1,82 @@
+<document source="index.md">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="test" names="test">
+        <title>
+            Test
+        <field_list classes="myst">
+            <field>
+                <field_name>
+                    field
+                <field_body>
+            <field>
+                <field_name>
+                    <emphasis>
+                        field
+                <field_body>
+                    <paragraph>
+                        content
+        <index entries="('pair',\ 'built-in\ function;\ send_message()',\ 'send_message',\ '',\ None)">
+        <desc classes="py" desctype="function" domain="py" noindex="False" objtype="function">
+            <desc_signature class="" fullname="send_message" ids="send_message" module="True">
+                <desc_name xml:space="preserve">
+                    send_message
+                <desc_parameterlist xml:space="preserve">
+                    <desc_parameter xml:space="preserve">
+                        <desc_sig_name classes="n">
+                            sender
+                    <desc_parameter xml:space="preserve">
+                        <desc_sig_name classes="n">
+                            priority
+            <desc_content>
+                <paragraph>
+                    Send a message to a recipient
+                <field_list classes="myst">
+                    <field>
+                        <field_name>
+                            Parameters
+                        <field_body>
+                            <bullet_list>
+                                <list_item>
+                                    <paragraph>
+                                        <literal_strong py:class="True" py:module="True" refspecific="True">
+                                            sender
+                                         (
+                                        <pending_xref py:class="True" py:module="True" refdomain="py" refexplicit="False" refspecific="True" reftarget="str" reftype="class">
+                                            <literal_emphasis>
+                                                str
+                                        )
+                                         – 
+                                        The person sending the message
+                                <list_item>
+                                    <paragraph>
+                                        <literal_strong py:class="True" py:module="True" refspecific="True">
+                                            priority
+                                         (
+                                        <pending_xref py:class="True" py:module="True" refdomain="py" refexplicit="False" refspecific="True" reftarget="int" reftype="class">
+                                            <literal_emphasis>
+                                                int
+                                        )
+                                         – 
+                                        The priority of the message, can be a number 1-5
+                    <field>
+                        <field_name>
+                            Returns
+                        <field_body>
+                            <paragraph>
+                                the message id
+                    <field>
+                        <field_name>
+                            Return type
+                        <field_body>
+                            <paragraph>
+                                <pending_xref py:class="True" py:module="True" refdomain="py" refexplicit="False" refspecific="True" reftarget="int" reftype="class">
+                                    int
+                    <field>
+                        <field_name>
+                            Raises
+                        <field_body>
+                            <paragraph>
+                                <pending_xref py:class="True" py:module="True" refdomain="py" refexplicit="False" refspecific="True" reftarget="ValueError" reftype="exc">
+                                    <literal_strong>
+                                        ValueError
+                                 – 
+                                if the message_body exceeds 160 characters
diff --git a/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx4.html b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx4.html
new file mode 100644
index 00000000..a4213a7b
--- /dev/null
+++ b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx4.html
@@ -0,0 +1,131 @@
+<div class="documentwrapper">
+ <div class="bodywrapper">
+  <div class="body" role="main">
+   <section class="tex2jax_ignore mathjax_ignore" id="test">
+    <h1>
+     Test
+     <a class="headerlink" href="#test" title="Permalink to this headline">
+      ¶
+     </a>
+    </h1>
+    <dl class="myst field-list simple">
+     <dt class="field-odd">
+      field
+     </dt>
+     <dd class="field-odd">
+      <p>
+      </p>
+     </dd>
+     <dt class="field-even">
+      <em>
+       field
+      </em>
+     </dt>
+     <dd class="field-even">
+      <p>
+       content
+      </p>
+     </dd>
+    </dl>
+    <dl class="py function">
+     <dt class="sig sig-object py" id="send_message">
+      <span class="sig-name descname">
+       <span class="pre">
+        send_message
+       </span>
+      </span>
+      <span class="sig-paren">
+       (
+      </span>
+      <em class="sig-param">
+       <span class="n">
+        <span class="pre">
+         sender
+        </span>
+       </span>
+      </em>
+      ,
+      <em class="sig-param">
+       <span class="n">
+        <span class="pre">
+         priority
+        </span>
+       </span>
+      </em>
+      <span class="sig-paren">
+       )
+      </span>
+      <a class="headerlink" href="#send_message" title="Permalink to this definition">
+       ¶
+      </a>
+     </dt>
+     <dd>
+      <p>
+       Send a message to a recipient
+      </p>
+      <dl class="myst field-list simple">
+       <dt class="field-odd">
+        Parameters
+       </dt>
+       <dd class="field-odd">
+        <ul class="simple">
+         <li>
+          <p>
+           <strong>
+            sender
+           </strong>
+           (
+           <em>
+            str
+           </em>
+           ) – The person sending the message
+          </p>
+         </li>
+         <li>
+          <p>
+           <strong>
+            priority
+           </strong>
+           (
+           <em>
+            int
+           </em>
+           ) – The priority of the message, can be a number 1-5
+          </p>
+         </li>
+        </ul>
+       </dd>
+       <dt class="field-even">
+        Returns
+       </dt>
+       <dd class="field-even">
+        <p>
+         the message id
+        </p>
+       </dd>
+       <dt class="field-odd">
+        Return type
+       </dt>
+       <dd class="field-odd">
+        <p>
+         int
+        </p>
+       </dd>
+       <dt class="field-even">
+        Raises
+       </dt>
+       <dd class="field-even">
+        <p>
+         <strong>
+          ValueError
+         </strong>
+         – if the message_body exceeds 160 characters
+        </p>
+       </dd>
+      </dl>
+     </dd>
+    </dl>
+   </section>
+  </div>
+ </div>
+</div>
diff --git a/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx4.xml b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx4.xml
new file mode 100644
index 00000000..7da41c10
--- /dev/null
+++ b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.sphinx4.xml
@@ -0,0 +1,82 @@
+<document source="index.md">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="test" names="test">
+        <title>
+            Test
+        <field_list classes="myst">
+            <field>
+                <field_name>
+                    field
+                <field_body>
+            <field>
+                <field_name>
+                    <emphasis>
+                        field
+                <field_body>
+                    <paragraph>
+                        content
+        <index entries="('pair',\ 'built-in\ function;\ send_message()',\ 'send_message',\ '',\ None)">
+        <desc classes="py function" desctype="function" domain="py" noindex="False" objtype="function">
+            <desc_signature class="" classes="sig sig-object" fullname="send_message" ids="send_message" module="True">
+                <desc_name classes="sig-name descname" xml:space="preserve">
+                    send_message
+                <desc_parameterlist xml:space="preserve">
+                    <desc_parameter xml:space="preserve">
+                        <desc_sig_name classes="n">
+                            sender
+                    <desc_parameter xml:space="preserve">
+                        <desc_sig_name classes="n">
+                            priority
+            <desc_content>
+                <paragraph>
+                    Send a message to a recipient
+                <field_list classes="myst">
+                    <field>
+                        <field_name>
+                            Parameters
+                        <field_body>
+                            <bullet_list>
+                                <list_item>
+                                    <paragraph>
+                                        <literal_strong py:class="True" py:module="True" refspecific="True">
+                                            sender
+                                         (
+                                        <pending_xref py:class="True" py:module="True" refdomain="py" refexplicit="False" refspecific="True" reftarget="str" reftype="class">
+                                            <literal_emphasis>
+                                                str
+                                        )
+                                         – 
+                                        The person sending the message
+                                <list_item>
+                                    <paragraph>
+                                        <literal_strong py:class="True" py:module="True" refspecific="True">
+                                            priority
+                                         (
+                                        <pending_xref py:class="True" py:module="True" refdomain="py" refexplicit="False" refspecific="True" reftarget="int" reftype="class">
+                                            <literal_emphasis>
+                                                int
+                                        )
+                                         – 
+                                        The priority of the message, can be a number 1-5
+                    <field>
+                        <field_name>
+                            Returns
+                        <field_body>
+                            <paragraph>
+                                the message id
+                    <field>
+                        <field_name>
+                            Return type
+                        <field_body>
+                            <paragraph>
+                                <pending_xref py:class="True" py:module="True" refdomain="py" refexplicit="False" refspecific="True" reftarget="int" reftype="class">
+                                    int
+                    <field>
+                        <field_name>
+                            Raises
+                        <field_body>
+                            <paragraph>
+                                <pending_xref py:class="True" py:module="True" refdomain="py" refexplicit="False" refspecific="True" reftarget="ValueError" reftype="exc">
+                                    <literal_strong>
+                                        ValueError
+                                 – 
+                                if the message_body exceeds 160 characters