From 80202cf4a8be7b5c4e2b9c6e2033e5a681140cf9 Mon Sep 17 00:00:00 2001 From: steppi <1953382+steppi@users.noreply.github.com> Date: Mon, 27 Jan 2025 13:35:13 -0500 Subject: [PATCH 1/3] Update list of docstring section headers --- jupyterlite_sphinx/_try_examples.py | 99 ++++++++++++++++------------- 1 file changed, 55 insertions(+), 44 deletions(-) diff --git a/jupyterlite_sphinx/_try_examples.py b/jupyterlite_sphinx/_try_examples.py index deb4f4d..fd27ed8 100755 --- a/jupyterlite_sphinx/_try_examples.py +++ b/jupyterlite_sphinx/_try_examples.py @@ -269,55 +269,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/latest/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 +345,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 ------- From aa19d80c6dad6213be3720acd48fdee1e221668f Mon Sep 17 00:00:00 2001 From: Albert Steppi <1953382+steppi@users.noreply.github.com> Date: Mon, 27 Jan 2025 20:17:26 -0500 Subject: [PATCH 2/3] Update jupyterlite_sphinx/_try_examples.py Co-authored-by: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> --- jupyterlite_sphinx/_try_examples.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jupyterlite_sphinx/_try_examples.py b/jupyterlite_sphinx/_try_examples.py index fd27ed8..90dea10 100755 --- a/jupyterlite_sphinx/_try_examples.py +++ b/jupyterlite_sphinx/_try_examples.py @@ -271,7 +271,7 @@ def _process_literal_blocks(md_text): # try_examples identifies section headers after processing by numpydoc or # sphinx.ext.napoleon. -# See https://numpydoc.readthedocs.io/en/latest/format.html for info on numpydoc +# 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 # for info on sphinx.ext.napoleon sections. From 6b8dfdb964d229d872b45f2cc03b03cf0753bd20 Mon Sep 17 00:00:00 2001 From: steppi <1953382+steppi@users.noreply.github.com> Date: Mon, 27 Jan 2025 20:19:06 -0500 Subject: [PATCH 3/3] Black fix code --- jupyterlite_sphinx/_try_examples.py | 1 + 1 file changed, 1 insertion(+) diff --git a/jupyterlite_sphinx/_try_examples.py b/jupyterlite_sphinx/_try_examples.py index 90dea10..2ef99f7 100755 --- a/jupyterlite_sphinx/_try_examples.py +++ b/jupyterlite_sphinx/_try_examples.py @@ -269,6 +269,7 @@ 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