Support Sphinx RST signatures

Author: krassowski

docstring_to_markdown/rst.py

@@ -6,10 +6,15 @@
 
 
 class Directive:
-    def __init__(self, pattern: str, replacement: str, name: Union[str, None] = None):
+    def __init__(
+        self, pattern: str, replacement: str,
+        name: Union[str, None] = None,
+        flags: int = 0
+    ):
         self.pattern = pattern
         self.replacement = replacement
         self.name = name
+        self.flags = flags
 
 
 # https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects
@@ -79,6 +84,15 @@ def __init__(self, pattern: str, replacement: str, name: Union[str, None] = None
     'term',
 )
 
+SPHINX_PARAM = (
+    'param',
+    'parameter',
+    'arg',
+    'argument',
+    'key',
+    'keyword'
+)
+
 SPHINX_RULES: List[Directive] = [
     Directive(
         pattern=r':c:({}):`\.?(?P<name>[^`]+?)`'.format('|'.join(SPHINX_CROSS_REF_C)),
@@ -109,13 +123,40 @@ def __init__(self, pattern: str, replacement: str, name: Union[str, None] = None
         replacement=r'`\g<name>`'
     ),
     Directive(
-        pattern=r'^:param (?P<param>\S+):',
-        replacement=r'- `\g<param>`:'
+        pattern=r'^\s*:({}) (?P<type>\S+) (?P<param>\S+):'.format('|'.join(SPHINX_PARAM)),
+        replacement=r'- `\g<param>` (`\g<type>`):',
+        flags=re.MULTILINE
     ),
     Directive(
-        pattern=r'^:return:',
-        replacement=r'Returns:'
-    )
+        pattern=r'^\s*:({}) (?P<param>\S+): (?P<desc>.*)(\n|\r\n?):type \2: (?P<type>.*)$'.format('|'.join(SPHINX_PARAM)),
+        replacement=r'- `\g<param>` (\g<type>): \g<desc>',
+        flags=re.MULTILINE
+    ),
+    Directive(
+        pattern=r'^\s*:({}) (?P<param>\S+):'.format('|'.join(SPHINX_PARAM)),
+        replacement=r'- `\g<param>`:',
+        flags=re.MULTILINE
+    ),
+    Directive(
+        pattern=r'^\s*:type (?P<param>\S+):',
+        replacement=r'  . Type: `\g<param>`:',
+        flags=re.MULTILINE
+    ),
+    Directive(
+        pattern=r'^\s*:(return|returns):',
+        replacement=r'- returns:',
+        flags=re.MULTILINE
+    ),
+    Directive(
+        pattern=r'^\s*:rtype: (?P<type>\S+)',
+        replacement=r'- return type: `\g<type>`',
+        flags=re.MULTILINE
+    ),
+    Directive(
+        pattern=r'^\s*:(raises|raise|except|exception) (?P<exception>\S+):',
+        replacement=r'- raises `\g<exception>`:',
+        flags=re.MULTILINE
+    ),
 ]
 
 
@@ -646,7 +687,7 @@ def flush_buffer():
         lines = '\n'.join(lines_buffer)
         # rst markup handling
         for directive in DIRECTIVES:
-            lines = re.sub(directive.pattern, directive.replacement, lines)
+            lines = re.sub(directive.pattern, directive.replacement, lines, flags=directive.flags)
 
         for (section, header) in RST_SECTIONS.items():
             lines = lines.replace(header, '\n#### ' + section + '\n')

tests/test_rst.py

@@ -624,6 +624,28 @@ def func(): pass
 """
 
 
+# https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists
+SPHINX_SIGNATURE = """
+:param str sender: The person sending the message
+:param str recipient: The recipient of the message
+:param str message_body: The body of the message
+:param priority: The priority of the message, can be a number 1-5
+:type priority: integer or None
+:return: the message id
+:rtype: int
+:raises ValueError: if the message_body exceeds 160 characters
+"""
+
+SPHINX_SIGNATURE_MARKDOWN = """\
+- `sender` (`str`): The person sending the message
+- `recipient` (`str`): The recipient of the message
+- `message_body` (`str`): The body of the message
+- `priority` (integer or None): The priority of the message, can be a number 1-5
+- returns: the message id
+- return type: `int`
+- raises `ValueError`: if the message_body exceeds 160 characters
+"""
+
 RST_CASES = {
     'handles prompt continuation and multi-line output': {
         'rst': CODE_MULTI_LINE_CODE_OUTPUT,
@@ -739,9 +761,9 @@ def func(): pass
         'rst': ':param x: test arg',
         'md': '- `x`: test arg'
     },
-    'converts sphinx return': {
-        'rst': ':return: return description',
-        'md': 'Returns: return description'
+    'converts indented sphinx params': {
+        'rst': '\t:param x: test arg',
+        'md': '- `x`: test arg'
     },
     'converts non-standard simple table': {
         'rst': SIMPLE_TABLE,
@@ -762,6 +784,10 @@ def func(): pass
     'converts nested parameter lists': {
         'rst': NESTED_PARAMETERS,
         'md': NESTED_PARAMETERS_MARKDOWN
+    },
+    'converts sphinx signatures': {
+        'rst': SPHINX_SIGNATURE,
+        'md': SPHINX_SIGNATURE_MARKDOWN
     }
 }