Skip to content

Commit 7702294

Browse files
BUG: Fix list of possible docstring section header patterns for global_enable_try_examples (#263)
Co-authored-by: Agriya Khetarpal <[email protected]>
1 parent f3c6381 commit 7702294

File tree

1 file changed

+55
-43
lines changed

1 file changed

+55
-43
lines changed

jupyterlite_sphinx/_try_examples.py

Lines changed: 55 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -270,54 +270,67 @@ def _process_literal_blocks(md_text):
270270
return "\n".join(new_lines)
271271

272272

273+
# try_examples identifies section headers after processing by numpydoc or
274+
# sphinx.ext.napoleon.
275+
# See https://numpydoc.readthedocs.io/en/stable/format.html for info on numpydoc
276+
# sections and
273277
# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections
274-
_non_example_docstring_section_headers = (
275-
"Args",
276-
"Arguments",
277-
"Attention",
278-
"Attributes",
279-
"Caution",
280-
"Danger",
281-
"Error",
282-
"Hint",
283-
"Important",
284-
"Keyword Args",
285-
"Keyword Arguments",
286-
"Methods",
287-
"Note",
288-
"Notes",
289-
"Other Parameters",
290-
"Parameters",
291-
"Return",
292-
"Returns",
293-
"Raise",
294-
"Raises",
295-
"References",
296-
"See Also",
297-
"Tip",
298-
"Todo",
299-
"Warning",
300-
"Warnings",
301-
"Warns",
302-
"Yield",
303-
"Yields",
304-
)
278+
# for info on sphinx.ext.napoleon sections.
305279

280+
# The patterns below were identified by creating a docstring using all section
281+
# headers and processing it with both numpydoc and sphinx.ext.napoleon.
306282

283+
# Examples section is a rubric for numpydoc and can be configured to be
284+
# either a rubric or admonition in sphinx.ext.napoleon.
307285
_examples_start_pattern = re.compile(r".. (rubric|admonition):: Examples")
308286
_next_section_pattern = re.compile(
309287
"|".join(
288+
# Newer versions of numpydoc enforce section order and only Attributes
289+
# and Methods sections can appear after an Examples section. All potential
290+
# numpydoc section headers are included here to support older or custom
291+
# numpydoc versions. e.g. at the time of this comment, SymPy is using a
292+
# custom version of numpydoc which allows for arbitrary section order.
293+
# sphinx.ext.napoleon allows for arbitrary section order and all potential
294+
# headers are included.
310295
[
311-
rf"\.\. (rubric|admonition)::\s*{header}"
312-
for header in _non_example_docstring_section_headers
296+
# Notes and References appear as rubrics in numpydoc and
297+
# can be configured to appear as either a rubric or
298+
# admonition in sphinx.ext.napoleon.
299+
r".\.\ rubric:: Notes",
300+
r".\.\ rubric:: References",
301+
r".\.\ admonition:: Notes",
302+
r".\.\ admonition:: References",
303+
# numpydoc only headers
304+
r":Attributes:",
305+
r".\.\ rubric:: Methods",
306+
r":Other Parameters:",
307+
r":Parameters:",
308+
r":Raises:",
309+
r":Returns:",
310+
# If examples section is last, processed by numpydoc may appear at end.
311+
r"\!\! processed by numpydoc \!\!",
312+
# sphinx.ext.napoleon only headers
313+
r"\.\. attribute::",
314+
r"\.\. method::",
315+
r":param .+:",
316+
r":raises .+:",
317+
r":returns:",
318+
# Headers generated by both extensions
319+
r".\.\ seealso::",
320+
r":Yields:",
321+
r":Warns:",
322+
# directives which can start a section with sphinx.ext.napoleon
323+
# with no equivalent when using numpydoc.
324+
r".\.\ attention::",
325+
r".\.\ caution::",
326+
r".\.\ danger::",
327+
r".\.\ error::",
328+
r".\.\ hint::",
329+
r".\.\ important::",
330+
r".\.\ tip::",
331+
r".\.\ todo::",
332+
r".\.\ warning::",
313333
]
314-
# If examples section is last, processed by numpydoc may appear at end.
315-
+ [r"\!\! processed by numpydoc \!\!"]
316-
# Attributes section sometimes has no directive.
317-
+ [r":Attributes:"]
318-
# See Also sections are mapped to Sphinx's `.. seealso::` directive,
319-
# not admonitions or rubrics.
320-
+ [r"\.\. seealso::"]
321334
)
322335
)
323336

@@ -333,9 +346,8 @@ def insert_try_examples_directive(lines, **options):
333346
Parameters
334347
----------
335348
docstring : list of str
336-
Lines of a docstring at time of "autodoc-process-docstring", with section
337-
headers denoted by `.. rubric::` or `.. admonition::`.
338-
349+
Lines of a docstring at time of "autodoc-process-docstring", which has
350+
been previously processed by numpydoc or sphinx.ext.napoleon.
339351
340352
Returns
341353
-------

0 commit comments

Comments
 (0)