Skip to content

Commit 04cb58f

Browse files
committed
Implement bibliographic references support
1 parent 96cd29d commit 04cb58f

File tree

2 files changed

+68
-24
lines changed

2 files changed

+68
-24
lines changed

docstring_to_markdown/rst.py

Lines changed: 40 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
from abc import ABC, abstractmethod
22
from types import SimpleNamespace
3-
from typing import Union, List
3+
from typing import Union, List, Dict
44
import re
55

66

@@ -68,6 +68,40 @@ def __init__(self, pattern: str, replacement: str, name: Union[str, None] = None
6868
)
6969
]
7070

71+
72+
_RST_SECTIONS = {
73+
'Parameters',
74+
'Returns',
75+
'See Also',
76+
'Examples',
77+
'Attributes',
78+
'Notes',
79+
'References'
80+
}
81+
82+
83+
# TODO: type with RstSection = Literal[], and generate _RST_SECTIONS out of it once
84+
# support for Python 3.6 can be safely dropped
85+
SECTION_DIRECTIVES: Dict[str, List[Directive]] = {
86+
'Parameters': [
87+
Directive(
88+
pattern=r'^(?P<other_args>\*\*kwargs|\*args)$',
89+
replacement=r'- `\g<other_args>`'
90+
),
91+
Directive(
92+
pattern=r'^(?P<arg1>[^:\s]+\d), (?P<arg2>[^:\s]+\d), \.\.\. : (?P<type>.+)$',
93+
replacement=r'- `\g<arg1>`, `\g<arg2>`, `...`: \g<type>'
94+
)
95+
],
96+
'References': [
97+
Directive(
98+
pattern=r'^\.\. \[(?P<number>\d+)\] (?P<first_line>.+)$',
99+
replacement=r'- [\g<number>] \g<first_line>'
100+
)
101+
]
102+
}
103+
104+
71105
ESCAPING_RULES: List[Directive] = [
72106
Directive(
73107
pattern=r'__(?P<text>\S+)__',
@@ -86,16 +120,6 @@ def _find_directive_pattern(name: str):
86120
HIGHLIGHT_PATTERN = _find_directive_pattern('highlight')
87121
CODE_BLOCK_PATTERN = _find_directive_pattern('code-block')
88122

89-
_RST_SECTIONS = {
90-
'Parameters',
91-
'Returns',
92-
'See Also',
93-
'Examples',
94-
'Attributes',
95-
'Notes',
96-
'References'
97-
}
98-
99123

100124
def looks_like_rst(value: str) -> bool:
101125
# check if any of the characteristic sections (and the properly formatted underline) is there
@@ -406,19 +430,12 @@ def flush_buffer():
406430
match = re.match(r'^(?P<argument>[^:\s]+) : (?P<type>.+)$', trimmed_line)
407431
if match:
408432
line = '- `' + match.group('argument') + '`: ' + match.group('type') + ''
409-
elif most_recent_section == 'Parameters':
410-
kwargs_or_args_match = re.match(r'^(?P<other_args>\*\*kwargs|\*args)$', trimmed_line)
411-
if kwargs_or_args_match:
412-
line = '- `' + kwargs_or_args_match.group('other_args') + '`'
413-
else:
414-
numpy_args_match = re.match(
415-
r'^(?P<arg1>[^:\s]+\d), (?P<arg2>[^:\s]+\d), \.\.\. : (?P<type>.+)$',
416-
trimmed_line
417-
)
418-
if numpy_args_match:
419-
groups = numpy_args_match.groupdict()
420-
line = f'- `{groups["arg1"]}`, `{groups["arg2"]}`, `...`: {groups["type"]}'
421433
else:
434+
if most_recent_section in SECTION_DIRECTIVES:
435+
for section_directive in SECTION_DIRECTIVES[most_recent_section]:
436+
if re.match(section_directive.pattern, trimmed_line):
437+
line = re.sub(section_directive.pattern, section_directive.replacement, trimmed_line)
438+
break
422439
if trimmed_line.rstrip() in RST_SECTIONS:
423440
most_recent_section = trimmed_line.rstrip()
424441

tests/test_rst.py

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -426,6 +426,29 @@ def func(): pass
426426
"""
427427

428428

429+
REFERENCES = """
430+
References
431+
----------
432+
.. [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra",
433+
Biometrika 37, 1-16, 1950.
434+
.. [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics",
435+
The University of Alberta Press, 1975, pp. 109-110.
436+
.. [3] Wikipedia, "Window function",
437+
https://en.wikipedia.org/wiki/Window_function
438+
"""
439+
440+
REFERENCES_MARKDOWN = """
441+
#### References
442+
443+
- [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra",
444+
Biometrika 37, 1-16, 1950.
445+
- [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics",
446+
The University of Alberta Press, 1975, pp. 109-110.
447+
- [3] Wikipedia, "Window function",
448+
https://en.wikipedia.org/wiki/Window_function
449+
"""
450+
451+
429452
INTEGRATION = """
430453
Return a fixed frequency DatetimeIndex.
431454
@@ -471,7 +494,7 @@ def func(): pass
471494
'rst': MATH_INLINE_BLOCK,
472495
'md': MATH_INLINE_BLOCK_MARKDOWN
473496
},
474-
'converts references': {
497+
'converts refs': {
475498
'rst': RST_REF_EXAMPLE,
476499
'md': RST_REF_MARKDOWN
477500
},
@@ -529,6 +552,10 @@ def func(): pass
529552
'rst': '__init__',
530553
'md': r'\_\_init\_\_'
531554
},
555+
'converts bibliographic references': {
556+
'rst': REFERENCES,
557+
'md': REFERENCES_MARKDOWN
558+
}
532559
}
533560

534561

0 commit comments

Comments
 (0)