@@ -270,54 +270,67 @@ def _process_literal_blocks(md_text):
270
270
return "\n " .join (new_lines )
271
271
272
272
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
273
277
# 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.
305
279
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.
306
282
283
+ # Examples section is a rubric for numpydoc and can be configured to be
284
+ # either a rubric or admonition in sphinx.ext.napoleon.
307
285
_examples_start_pattern = re .compile (r".. (rubric|admonition):: Examples" )
308
286
_next_section_pattern = re .compile (
309
287
"|" .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.
310
295
[
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::" ,
313
333
]
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::" ]
321
334
)
322
335
)
323
336
@@ -333,9 +346,8 @@ def insert_try_examples_directive(lines, **options):
333
346
Parameters
334
347
----------
335
348
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.
339
351
340
352
Returns
341
353
-------
0 commit comments