ENH: Add support for reST-style docstrings

pdoc/html_helpers.py

@@ -265,6 +265,71 @@ def googledoc_sections(match):
                           r'((?:\n?(?: {2,}.*|$))+)', re.MULTILINE).sub(googledoc_sections, text)
         return text
 
+    @staticmethod
+    def reST(text: str) -> str:
+        """
+        Convert `text` in reST-style docstring format to Markdown
+        to be further converted later.
+        """
+        def reST_sections(match) -> str:
+            # E.g. for ":param arg1: Text" tag is "param", name is "arg1", and body is "Text"
+            tag, name, body = match.groups('')
+            body = textwrap.dedent(body)
+
+            type_ = None
+            nonlocal active_section
+            active_section_changed = False
+
+            if tag in ['type', 'rtype']:
+                return ''
+            elif tag in ('param', 'parameter', 'arg', 'argument', 'key', 'keyword'):
+                type_ = parameter_types.get(name, None)
+
+                if active_section != 'Args':
+                    active_section = 'Args'
+                    active_section_changed = True
+            elif tag in ('return', 'returns'):
+                if len(return_types) > 0:
+                    type_ = return_types.pop()
+
+                if active_section != 'Returns':
+                    active_section = 'Returns'
+                    active_section_changed = True
+            elif tag in ('raise', 'raises'):
+                if active_section != 'Raises':
+                    active_section = 'Raises'
+                    active_section_changed = True
+
+            if name or type_:
+                text = _ToMarkdown._deflist(*_ToMarkdown._fix_indent(name, type_, body))
+            else:
+                _, _, body = _ToMarkdown._fix_indent(name, type_, body)
+                text = f':   {body}'
+
+            if active_section_changed:
+                text = f'\n{active_section}:\n-----=\n{text}'
+            else:
+                text = f'\n{text}'
+
+            return text
+
+        regex = re.compile(r'^:(\S+)(?:\s(\S+?))?:((?:\n?(?: .*|$))+)', re.MULTILINE)
+
+        # Get all parameter and return types beforehand, to then use them when substituting
+        # the sections
+        parameter_types = {}
+        return_types = []
+        for tag, name, body in regex.findall(text):
+            if tag == 'type':
+                parameter_types[name] = body.strip()
+            elif tag == 'rtype':
+                return_types.append(body.strip())
+
+        active_section = None  # Keep track of the currently active section (e.g. Args, Returns)
+        text = regex.sub(reST_sections, text)
+
+        return text
+
     @staticmethod
     def _admonition(match, module=None, limit_types=None):
         indent, type, value, text = match.groups()
@@ -406,8 +471,9 @@ def to_html(text: str, *,
             latex_math: bool = False):
     """
     Returns HTML of `text` interpreted as `docformat`. `__docformat__` is respected
-    if present, otherwise Numpydoc and Google-style docstrings are assumed,
-    as well as pure Markdown.
+    if present, otherwise it is inferred whether it's reST-style, or Numpydoc
+    and Google-style docstrings. Pure Markdown and reST directives are also assumed
+    and processed if docformat has not been specified.
 
     `module` should be the documented module (so the references can be
     resolved) and `link` is the hyperlinking function like the one in the
@@ -430,20 +496,35 @@ def to_markdown(text: str, *,
                 module: pdoc.Module = None, link: Callable[..., str] = None):
     """
     Returns `text`, assumed to be a docstring in `docformat`, converted to markdown.
-    `__docformat__` is respected
-    if present, otherwise Numpydoc and Google-style docstrings are assumed,
-    as well as pure Markdown.
+    `__docformat__` is respected if present, otherwise it is inferred whether it's
+     reST-style, or Numpydoc and Google-style docstrings. Pure Markdown and reST directives
+     are also assumed and processed if docformat has not been specified.
 
     `module` should be the documented module (so the references can be
     resolved) and `link` is the hyperlinking function like the one in the
     example template.
     """
     if not docformat:
-        docformat = str(getattr(getattr(module, 'obj', None), '__docformat__', 'numpy,google '))
+        docformat = str(getattr(getattr(module, 'obj', None), '__docformat__', ''))
+
+        # Infer docformat if it hasn't been specified
+        if docformat == '':
+            reST_tags = ['param', 'arg', 'type', 'raise', 'except', 'return', 'rtype']
+            reST_regex = fr'^:(?:{"|".join(reST_tags)}).*?:'
+            found_reST_tags = re.findall(reST_regex, text, re.MULTILINE)
+
+            # Assume reST-style docstring if any of the above specified tags is present at the beginning of a line.
+            # Could make this more robust, e.g., by checking against the amount of found google or numpy tags
+            if len(found_reST_tags) > 0:
+                docformat = 'reST '
+            else:
+                docformat = 'numpy,google '
+
         docformat, *_ = docformat.lower().split()
-    if not (set(docformat.split(',')) & {'', 'numpy', 'google'}):
+
+    if not (set(docformat.split(',')) & {'', 'numpy', 'google', 'rest'}):
         warn('__docformat__ value {!r} in module {!r} not supported. '
-             'Supported values are: numpy, google.'.format(docformat, module))
+             'Supported values are: numpy, google, reST.'.format(docformat, module))
         docformat = 'numpy,google'
 
     with _fenced_code_blocks_hidden(text) as result:
@@ -462,6 +543,9 @@ def to_markdown(text: str, *,
         if 'numpy' in docformat:
             text = _ToMarkdown.numpy(text)
 
+        if 'rest' in docformat:
+            text = _ToMarkdown.reST(text)
+
         if module and link:
             # Hyperlink markdown code spans not within markdown hyperlinks.
             # E.g. `code` yes, but not [`code`](...). RE adapted from:

pdoc/test/__init__.py

@@ -1403,6 +1403,36 @@ def test_google(self):
         html = to_html(text, module=self._module, link=self._link)
         self.assertEqual(html, expected)
 
+    def test_reST(self):
+        expected = '''<p>Summary line.</p>
+<h2 id="args">Args:</h2>
+<dl>
+<dt><strong><code>arg1</code></strong> :&ensp;<code>int</code></dt>
+<dd>Text1</dd>
+<dt><strong><code>arg2</code></strong> :&ensp;<code>Optional[List[Tuple[str]]]</code></dt>
+<dd>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
+ diam nonumy eirmod tempor invidunt</dd>
+<dt><strong><code>arg_arg_3</code></strong> :&ensp;<code>Dict[int, Dict[str, Any]]</code></dt>
+<dd>Y:=H^T<em>X!@#$%^&amp;&amp;</em>()_[]{}';'::</dd>
+</dl>
+<h2 id="returns">Returns:</h2>
+<dl>
+<dt><code>bool</code></dt>
+<dd>True. Or False. Depends</dd>
+<dd>Now with more "s"</dd>
+</dl>
+<h2 id="raises">Raises:</h2>
+<dl>
+<dt><strong><code>Exception</code></strong></dt>
+<dd>Raised occasionally</dd>
+<dt><strong><code>ZeroDivisionError</code></strong></dt>
+<dd>You know why and when</dd>
+</dl>'''
+        text = inspect.getdoc(self._docmodule.reST)
+        html = to_html(text, module=self._module, link=self._link)
+
+        self.assertEqual(html, expected)
+
     def test_doctests(self):
         expected = '''<p>Need an intro paragrapgh.</p>
 <pre><code>&gt;&gt;&gt; Then code is indented one level

pdoc/test/example_pkg/__init__.py

@@ -298,6 +298,25 @@ def doctests(self):
             Exception: something went wrong
         """
 
+    def reST(self):
+        """
+        Summary line.
+
+        :param arg1: Text1
+        :parameter arg2: Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
+            diam nonumy eirmod tempor invidunt
+        :arg arg_arg_3: Y:=H^T*X!@#$%^&&*()_[]{}';'::
+        :type arg1: int
+        :type arg2: Optional[List[Tuple[str]]]
+        :type arg_arg_3: Dict[int, Dict[str, Any]]
+        :return: True. Or False. Depends
+        :rtype: bool
+
+        :returns: Now with more "s"
+        :raise Exception: Raised occasionally
+        :raises ZeroDivisionError: You know why and when
+        """
+
     def reST_directives(self):
         """
         .. todo::
@@ -345,6 +364,9 @@ def reST_directives(self):
 doctests = Docformats.doctests
 
 
+reST = Docformats.reST
+
+
 reST_directives = Docformats.reST_directives