Skip to content

Commit 90bdf42

Browse files
committed
Add initial support for some common sphinx rules
1 parent 2c62b18 commit 90bdf42

File tree

2 files changed

+35
-5
lines changed

2 files changed

+35
-5
lines changed

docstring_to_markdown/rst.py

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,22 @@ def __init__(self, pattern: str, replacement: str, name: Union[str, None] = None
1111
self.name = name
1212

1313

14+
SPHINX_RULES: List[Directive] = [
15+
Directive(
16+
pattern=r':(func|meth|class):`\.?(?P<name>[^`]+?)`',
17+
replacement=r'`\g<name>`'
18+
),
19+
Directive(
20+
pattern=r'^:param (?P<param>\S+):',
21+
replacement=r'- `\g<param>`:'
22+
),
23+
Directive(
24+
pattern=r'^:return:',
25+
replacement=r'Returns:'
26+
)
27+
]
28+
29+
1430
RST_DIRECTIVES: List[Directive] = [
1531
Directive(
1632
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
6581
pattern=r'\.\. (code-block|productionlist)::(?P<language>.*)(?P<end>$|\n)',
6682
replacement=r'\g<end>',
6783
name='code-block'
68-
)
84+
),
85+
*SPHINX_RULES
6986
]
7087

7188

@@ -96,7 +113,7 @@ def __init__(self, pattern: str, replacement: str, name: Union[str, None] = None
96113
'References': [
97114
Directive(
98115
pattern=r'^\.\. \[(?P<number>\d+)\] (?P<first_line>.+)$',
99-
replacement=r'- [\g<number>] \g<first_line>'
116+
replacement=r' - [\g<number>] \g<first_line>'
100117
)
101118
]
102119
}

tests/test_rst.py

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@
7777
"To learn more about the frequency strings, please see "
7878
"[this link](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)."
7979
)
80+
8081
RST_REF_EXAMPLE = """See :ref:`here <timeseries.offset_aliases>` for a list of frequency aliases."""
8182
RST_REF_MARKDOWN = """See here: `timeseries.offset_aliases` for a list of frequency aliases."""
8283

@@ -440,11 +441,11 @@ def func(): pass
440441
REFERENCES_MARKDOWN = """
441442
#### References
442443
443-
- [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra",
444+
- [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra",
444445
Biometrika 37, 1-16, 1950.
445-
- [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics",
446+
- [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics",
446447
The University of Alberta Press, 1975, pp. 109-110.
447-
- [3] Wikipedia, "Window function",
448+
- [3] Wikipedia, "Window function",
448449
https://en.wikipedia.org/wiki/Window_function
449450
"""
450451

@@ -555,6 +556,18 @@ def func(): pass
555556
'converts bibliographic references': {
556557
'rst': REFERENCES,
557558
'md': REFERENCES_MARKDOWN
559+
},
560+
'converts sphinx func, meth, and class': {
561+
'rst': ':func:`function1`, :meth:`.Script.inline`, :class:`.Environment`',
562+
'md': '`function1`, `Script.inline`, `Environment`'
563+
},
564+
'converts sphinx params': {
565+
'rst': ':param x: test arg',
566+
'md': '- `x`: test arg'
567+
},
568+
'converts sphinx return': {
569+
'rst': ':return: return description',
570+
'md': 'Returns: return description'
558571
}
559572
}
560573

0 commit comments

Comments
 (0)