Implement bibliographic references support

Author: krassowski

docstring_to_markdown/rst.py

@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 from types import SimpleNamespace
-from typing import Union, List
+from typing import Union, List, Dict
 import re
 
 
@@ -68,6 +68,40 @@ def __init__(self, pattern: str, replacement: str, name: Union[str, None] = None
     )
 ]
 
+
+_RST_SECTIONS = {
+    'Parameters',
+    'Returns',
+    'See Also',
+    'Examples',
+    'Attributes',
+    'Notes',
+    'References'
+}
+
+
+# TODO: type with RstSection = Literal[], and generate _RST_SECTIONS out of it once
+#  support for Python 3.6 can be safely dropped
+SECTION_DIRECTIVES: Dict[str, List[Directive]] = {
+    'Parameters': [
+        Directive(
+            pattern=r'^(?P<other_args>\*\*kwargs|\*args)$',
+            replacement=r'- `\g<other_args>`'
+        ),
+        Directive(
+            pattern=r'^(?P<arg1>[^:\s]+\d), (?P<arg2>[^:\s]+\d), \.\.\. : (?P<type>.+)$',
+            replacement=r'- `\g<arg1>`, `\g<arg2>`, `...`: \g<type>'
+        )
+    ],
+    'References': [
+        Directive(
+            pattern=r'^\.\. \[(?P<number>\d+)\] (?P<first_line>.+)$',
+            replacement=r'- [\g<number>] \g<first_line>'
+        )
+    ]
+}
+
+
 ESCAPING_RULES: List[Directive] = [
     Directive(
         pattern=r'__(?P<text>\S+)__',
@@ -86,16 +120,6 @@ def _find_directive_pattern(name: str):
 HIGHLIGHT_PATTERN = _find_directive_pattern('highlight')
 CODE_BLOCK_PATTERN = _find_directive_pattern('code-block')
 
-_RST_SECTIONS = {
-    'Parameters',
-    'Returns',
-    'See Also',
-    'Examples',
-    'Attributes',
-    'Notes',
-    'References'
-}
-
 
 def looks_like_rst(value: str) -> bool:
     # check if any of the characteristic sections (and the properly formatted underline) is there
@@ -406,19 +430,12 @@ def flush_buffer():
             match = re.match(r'^(?P<argument>[^:\s]+) : (?P<type>.+)$', trimmed_line)
             if match:
                 line = '- `' + match.group('argument') + '`: ' + match.group('type') + ''
-            elif most_recent_section == 'Parameters':
-                kwargs_or_args_match = re.match(r'^(?P<other_args>\*\*kwargs|\*args)$', trimmed_line)
-                if kwargs_or_args_match:
-                    line = '- `' + kwargs_or_args_match.group('other_args') + '`'
-                else:
-                    numpy_args_match = re.match(
-                        r'^(?P<arg1>[^:\s]+\d), (?P<arg2>[^:\s]+\d), \.\.\. : (?P<type>.+)$',
-                        trimmed_line
-                    )
-                    if numpy_args_match:
-                        groups = numpy_args_match.groupdict()
-                        line = f'- `{groups["arg1"]}`, `{groups["arg2"]}`, `...`: {groups["type"]}'
             else:
+                if most_recent_section in SECTION_DIRECTIVES:
+                    for section_directive in SECTION_DIRECTIVES[most_recent_section]:
+                        if re.match(section_directive.pattern, trimmed_line):
+                            line = re.sub(section_directive.pattern, section_directive.replacement, trimmed_line)
+                            break
                 if trimmed_line.rstrip() in RST_SECTIONS:
                     most_recent_section = trimmed_line.rstrip()
 

tests/test_rst.py

@@ -426,6 +426,29 @@ def func(): pass
 """
 
 
+REFERENCES = """
+References
+----------
+.. [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra",
+   Biometrika 37, 1-16, 1950.
+.. [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics",
+   The University of Alberta Press, 1975, pp. 109-110.
+.. [3] Wikipedia, "Window function",
+   https://en.wikipedia.org/wiki/Window_function
+"""
+
+REFERENCES_MARKDOWN = """
+#### References
+
+- [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra",
+   Biometrika 37, 1-16, 1950.
+- [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics",
+   The University of Alberta Press, 1975, pp. 109-110.
+- [3] Wikipedia, "Window function",
+   https://en.wikipedia.org/wiki/Window_function
+"""
+
+
 INTEGRATION = """
 Return a fixed frequency DatetimeIndex.
 
@@ -471,7 +494,7 @@ def func(): pass
         'rst': MATH_INLINE_BLOCK,
         'md': MATH_INLINE_BLOCK_MARKDOWN
     },
-    'converts references': {
+    'converts refs': {
         'rst': RST_REF_EXAMPLE,
         'md': RST_REF_MARKDOWN
     },
@@ -529,6 +552,10 @@ def func(): pass
         'rst': '__init__',
         'md': r'\_\_init\_\_'
     },
+    'converts bibliographic references': {
+        'rst': REFERENCES,
+        'md': REFERENCES_MARKDOWN
+    }
 }