BUG: Fix list of possible docstring section header patterns for global_enable_try_examples (#263)

Co-authored-by: Agriya Khetarpal <[email protected]>

Author: steppi

jupyterlite_sphinx/_try_examples.py

@@ -270,54 +270,67 @@ def _process_literal_blocks(md_text):
     return "\n".join(new_lines)
 
 
+# try_examples identifies section headers after processing by numpydoc or
+# sphinx.ext.napoleon.
+# See https://numpydoc.readthedocs.io/en/stable/format.html for info on numpydoc
+# sections and
 # https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections
-_non_example_docstring_section_headers = (
-    "Args",
-    "Arguments",
-    "Attention",
-    "Attributes",
-    "Caution",
-    "Danger",
-    "Error",
-    "Hint",
-    "Important",
-    "Keyword Args",
-    "Keyword Arguments",
-    "Methods",
-    "Note",
-    "Notes",
-    "Other Parameters",
-    "Parameters",
-    "Return",
-    "Returns",
-    "Raise",
-    "Raises",
-    "References",
-    "See Also",
-    "Tip",
-    "Todo",
-    "Warning",
-    "Warnings",
-    "Warns",
-    "Yield",
-    "Yields",
-)
+# for info on sphinx.ext.napoleon sections.
 
+# The patterns below were identified by creating a docstring using all section
+# headers and processing it with both numpydoc and sphinx.ext.napoleon.
 
+# Examples section is a rubric for numpydoc and can be configured to be
+# either a rubric or admonition in sphinx.ext.napoleon.
 _examples_start_pattern = re.compile(r".. (rubric|admonition):: Examples")
 _next_section_pattern = re.compile(
     "|".join(
+        # Newer versions of numpydoc enforce section order and only Attributes
+        # and Methods sections can appear after an Examples section. All potential
+        # numpydoc section headers are included here to support older or custom
+        # numpydoc versions. e.g. at the time of this comment, SymPy is using a
+        # custom version of numpydoc which allows for arbitrary section order.
+        # sphinx.ext.napoleon allows for arbitrary section order and all potential
+        # headers are included.
         [
-            rf"\.\. (rubric|admonition)::\s*{header}"
-            for header in _non_example_docstring_section_headers
+            # Notes and References appear as rubrics in numpydoc and
+            # can be configured to appear as either a rubric or
+            # admonition in sphinx.ext.napoleon.
+            r".\.\ rubric:: Notes",
+            r".\.\ rubric:: References",
+            r".\.\ admonition:: Notes",
+            r".\.\ admonition:: References",
+            # numpydoc only headers
+            r":Attributes:",
+            r".\.\ rubric:: Methods",
+            r":Other Parameters:",
+            r":Parameters:",
+            r":Raises:",
+            r":Returns:",
+            # If examples section is last, processed by numpydoc may appear at end.
+            r"\!\! processed by numpydoc \!\!",
+            # sphinx.ext.napoleon only headers
+            r"\.\. attribute::",
+            r"\.\. method::",
+            r":param .+:",
+            r":raises .+:",
+            r":returns:",
+            # Headers generated by both extensions
+            r".\.\ seealso::",
+            r":Yields:",
+            r":Warns:",
+            # directives which can start a section with sphinx.ext.napoleon
+            # with no equivalent when using numpydoc.
+            r".\.\ attention::",
+            r".\.\ caution::",
+            r".\.\ danger::",
+            r".\.\ error::",
+            r".\.\ hint::",
+            r".\.\ important::",
+            r".\.\ tip::",
+            r".\.\ todo::",
+            r".\.\ warning::",
         ]
-        # If examples section is last, processed by numpydoc may appear at end.
-        + [r"\!\! processed by numpydoc \!\!"]
-        # Attributes section sometimes has no directive.
-        + [r":Attributes:"]
-        # See Also sections are mapped to Sphinx's `.. seealso::` directive,
-        # not admonitions or rubrics.
-        + [r"\.\. seealso::"]
     )
 )
 
@@ -333,9 +346,8 @@ def insert_try_examples_directive(lines, **options):
     Parameters
     ----------
     docstring : list of str
-        Lines of a docstring at time of "autodoc-process-docstring", with section
-        headers denoted by `.. rubric::` or `.. admonition::`.
-
+        Lines of a docstring at time of "autodoc-process-docstring", which has
+        been previously processed by numpydoc or sphinx.ext.napoleon.
 
     Returns
     -------