Add initial support for some common sphinx rules

Author: krassowski

docstring_to_markdown/rst.py

@@ -11,6 +11,22 @@ def __init__(self, pattern: str, replacement: str, name: Union[str, None] = None
         self.name = name
 
 
+SPHINX_RULES: List[Directive] = [
+    Directive(
+        pattern=r':(func|meth|class):`\.?(?P<name>[^`]+?)`',
+        replacement=r'`\g<name>`'
+    ),
+    Directive(
+        pattern=r'^:param (?P<param>\S+):',
+        replacement=r'- `\g<param>`:'
+    ),
+    Directive(
+        pattern=r'^:return:',
+        replacement=r'Returns:'
+    )
+]
+
+
 RST_DIRECTIVES: List[Directive] = [
     Directive(
         pattern=r'\.\. versionchanged:: (?P<version>\S+)(?P<end>$|\n)',
@@ -65,7 +81,8 @@ def __init__(self, pattern: str, replacement: str, name: Union[str, None] = None
         pattern=r'\.\. (code-block|productionlist)::(?P<language>.*)(?P<end>$|\n)',
         replacement=r'\g<end>',
         name='code-block'
-    )
+    ),
+    *SPHINX_RULES
 ]
 
 
@@ -96,7 +113,7 @@ def __init__(self, pattern: str, replacement: str, name: Union[str, None] = None
     'References': [
         Directive(
             pattern=r'^\.\. \[(?P<number>\d+)\] (?P<first_line>.+)$',
-            replacement=r'- [\g<number>] \g<first_line>'
+            replacement=r' - [\g<number>] \g<first_line>'
         )
     ]
 }

tests/test_rst.py

@@ -77,6 +77,7 @@
     "To learn more about the frequency strings, please see "
     "[this link](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)."
 )
+
 RST_REF_EXAMPLE = """See :ref:`here <timeseries.offset_aliases>` for a list of frequency aliases."""
 RST_REF_MARKDOWN = """See here: `timeseries.offset_aliases` for a list of frequency aliases."""
 
@@ -440,11 +441,11 @@ def func(): pass
 REFERENCES_MARKDOWN = """
 #### References
 
-- [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra",
+ - [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra",
    Biometrika 37, 1-16, 1950.
-- [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics",
+ - [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics",
    The University of Alberta Press, 1975, pp. 109-110.
-- [3] Wikipedia, "Window function",
+ - [3] Wikipedia, "Window function",
    https://en.wikipedia.org/wiki/Window_function
 """
 
@@ -555,6 +556,18 @@ def func(): pass
     'converts bibliographic references': {
         'rst': REFERENCES,
         'md': REFERENCES_MARKDOWN
+    },
+    'converts sphinx func, meth, and class': {
+        'rst': ':func:`function1`, :meth:`.Script.inline`, :class:`.Environment`',
+        'md': '`function1`, `Script.inline`, `Environment`'
+    },
+    'converts sphinx params': {
+        'rst': ':param x: test arg',
+        'md': '- `x`: test arg'
+    },
+    'converts sphinx return': {
+        'rst': ':return: return description',
+        'md': 'Returns: return description'
     }
 }