From f24cd2dd79a4e31bbed8d71577eabfed8c4a2de2 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sat, 11 Jan 2025 04:25:07 +0530 Subject: [PATCH 1/7] Add `..seealso` section as a pattern --- jupyterlite_sphinx/_try_examples.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/jupyterlite_sphinx/_try_examples.py b/jupyterlite_sphinx/_try_examples.py index bbd3f78f..60c6abd3 100755 --- a/jupyterlite_sphinx/_try_examples.py +++ b/jupyterlite_sphinx/_try_examples.py @@ -315,6 +315,10 @@ def _process_literal_blocks(md_text): + [r"\!\! processed by numpydoc \!\!"] # Attributes section sometimes has no directive. + [r":Attributes:"] + # The See Also section shows up for old numpydoc versions where ordering + # is neither guaranteed nor enforced; such as SymPy, therefore we check + # for it as a special case. + + [r".. seealso::"] ) ) From 10abc82a39e8975727fb5ef2ddb77a400158c534 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sun, 12 Jan 2025 04:32:14 +0530 Subject: [PATCH 2/7] Fix escaping of regex characters Co-Authored-By: Albert Steppi <1953382+steppi@users.noreply.github.com> --- jupyterlite_sphinx/_try_examples.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jupyterlite_sphinx/_try_examples.py b/jupyterlite_sphinx/_try_examples.py index 60c6abd3..87d3eac3 100755 --- a/jupyterlite_sphinx/_try_examples.py +++ b/jupyterlite_sphinx/_try_examples.py @@ -308,7 +308,7 @@ def _process_literal_blocks(md_text): _next_section_pattern = re.compile( "|".join( [ - rf".. (rubric|admonition)::\s*{header}" + rf"\.\. (rubric|admonition)::\s*{header}" for header in _non_example_docstring_section_headers ] # If examples section is last, processed by numpydoc may appear at end. @@ -318,7 +318,7 @@ def _process_literal_blocks(md_text): # The See Also section shows up for old numpydoc versions where ordering # is neither guaranteed nor enforced; such as SymPy, therefore we check # for it as a special case. - + [r".. seealso::"] + + [r"\.\. seealso::"] ) ) From 5f187f3272fbc0404d4ba437adcfc5e5df1205f3 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Sun, 12 Jan 2025 20:05:49 +0530 Subject: [PATCH 3/7] Reword comment about SymPy's special case Co-Authored-By: Albert Steppi <1953382+steppi@users.noreply.github.com> --- jupyterlite_sphinx/_try_examples.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/jupyterlite_sphinx/_try_examples.py b/jupyterlite_sphinx/_try_examples.py index 87d3eac3..87f25f79 100755 --- a/jupyterlite_sphinx/_try_examples.py +++ b/jupyterlite_sphinx/_try_examples.py @@ -315,9 +315,9 @@ def _process_literal_blocks(md_text): + [r"\!\! processed by numpydoc \!\!"] # Attributes section sometimes has no directive. + [r":Attributes:"] - # The See Also section shows up for old numpydoc versions where ordering - # is neither guaranteed nor enforced; such as SymPy, therefore we check - # for it as a special case. + # The See Also section shows up for old numpydoc versions such as that + # of SymPy where it is accounted for as an admonition and not a rubric, + # therefore we check for it as a special case for now. + [r"\.\. seealso::"] ) ) From 79e864e2b5107842fdc2a93d8159f0362245feba Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Mon, 13 Jan 2025 05:49:09 +0530 Subject: [PATCH 4/7] Add subset of docutils + Sphinx directives to end at --- jupyterlite_sphinx/_try_examples.py | 30 +++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/jupyterlite_sphinx/_try_examples.py b/jupyterlite_sphinx/_try_examples.py index 87f25f79..252d4696 100755 --- a/jupyterlite_sphinx/_try_examples.py +++ b/jupyterlite_sphinx/_try_examples.py @@ -303,6 +303,28 @@ def _process_literal_blocks(md_text): "Yields", ) +# Sourced from docutils.parsers.rst.directives._directive_registry.keys() +# and from https://docutils.sourceforge.io/docs/ref/rst/directives.html +# We hardcode a subset of this list as there is no public API in docutils +# or Sphinx to get this information directly. +# See https://docutils.sourceforge.io/docs/ref/rst/directives.html +# +# This subset is only a list of sensible defaults and widely used directives +# based on our discretion that can signify the start of a new section in a +# docstring and is not meant to be exhaustive. +_irrelevant_directives = [ + "class", + "contents", + "epigraph", + "footer", + "header", + "highlights", + "parsed-literal", + "pull-quote", + "seealso", + "sidebar", + "topic", +] _examples_start_pattern = re.compile(r".. (rubric|admonition):: Examples") _next_section_pattern = re.compile( @@ -315,10 +337,10 @@ def _process_literal_blocks(md_text): + [r"\!\! processed by numpydoc \!\!"] # Attributes section sometimes has no directive. + [r":Attributes:"] - # The See Also section shows up for old numpydoc versions such as that - # of SymPy where it is accounted for as an admonition and not a rubric, - # therefore we check for it as a special case for now. - + [r"\.\. seealso::"] + # Directives that can start a new section in a docstring and are + # not handled by numpydoc in terms of reordering. Noticed in SymPy + # as it does not use modern numpydoc at the time of writing. + + [rf"\.\. ({directive})::" for directive in _irrelevant_directives] ) ) From 08e70bd0d91e66cecbc8c5fd9073e85ac9965c34 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Mon, 13 Jan 2025 21:27:33 +0530 Subject: [PATCH 5/7] Revert "Add subset of docutils + Sphinx directives to end at" This reverts commit 79e864e2b5107842fdc2a93d8159f0362245feba. --- jupyterlite_sphinx/_try_examples.py | 30 ++++------------------------- 1 file changed, 4 insertions(+), 26 deletions(-) diff --git a/jupyterlite_sphinx/_try_examples.py b/jupyterlite_sphinx/_try_examples.py index 252d4696..87f25f79 100755 --- a/jupyterlite_sphinx/_try_examples.py +++ b/jupyterlite_sphinx/_try_examples.py @@ -303,28 +303,6 @@ def _process_literal_blocks(md_text): "Yields", ) -# Sourced from docutils.parsers.rst.directives._directive_registry.keys() -# and from https://docutils.sourceforge.io/docs/ref/rst/directives.html -# We hardcode a subset of this list as there is no public API in docutils -# or Sphinx to get this information directly. -# See https://docutils.sourceforge.io/docs/ref/rst/directives.html -# -# This subset is only a list of sensible defaults and widely used directives -# based on our discretion that can signify the start of a new section in a -# docstring and is not meant to be exhaustive. -_irrelevant_directives = [ - "class", - "contents", - "epigraph", - "footer", - "header", - "highlights", - "parsed-literal", - "pull-quote", - "seealso", - "sidebar", - "topic", -] _examples_start_pattern = re.compile(r".. (rubric|admonition):: Examples") _next_section_pattern = re.compile( @@ -337,10 +315,10 @@ def _process_literal_blocks(md_text): + [r"\!\! processed by numpydoc \!\!"] # Attributes section sometimes has no directive. + [r":Attributes:"] - # Directives that can start a new section in a docstring and are - # not handled by numpydoc in terms of reordering. Noticed in SymPy - # as it does not use modern numpydoc at the time of writing. - + [rf"\.\. ({directive})::" for directive in _irrelevant_directives] + # The See Also section shows up for old numpydoc versions such as that + # of SymPy where it is accounted for as an admonition and not a rubric, + # therefore we check for it as a special case for now. + + [r"\.\. seealso::"] ) ) From 53971807b2917b1b5f76c8f8e18c23111a84d11f Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Mon, 13 Jan 2025 21:30:36 +0530 Subject: [PATCH 6/7] Reword comment about "See Also" section Co-Authored-By: Albert Steppi <1953382+steppi@users.noreply.github.com> --- jupyterlite_sphinx/_try_examples.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/jupyterlite_sphinx/_try_examples.py b/jupyterlite_sphinx/_try_examples.py index 87f25f79..4a2b1067 100755 --- a/jupyterlite_sphinx/_try_examples.py +++ b/jupyterlite_sphinx/_try_examples.py @@ -315,9 +315,12 @@ def _process_literal_blocks(md_text): + [r"\!\! processed by numpydoc \!\!"] # Attributes section sometimes has no directive. + [r":Attributes:"] - # The See Also section shows up for old numpydoc versions such as that - # of SymPy where it is accounted for as an admonition and not a rubric, - # therefore we check for it as a special case for now. + # The See Also section is also a heading that needs to be escaped. This + # showed up in the SymPy documentation which used an older version of + # numpydoc that did not enforce ordering, and modern numpydoc did, hence + # it was not noticed. For future reference, see: + # https://github.com/jupyterlite/jupyterlite-sphinx/pull/251 + # https://github.com/sympy/sympy/pull/27419 + [r"\.\. seealso::"] ) ) From 631dfeb0c4ca08a99d60c3fb11c36059f31eea1b Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Mon, 13 Jan 2025 22:02:48 +0530 Subject: [PATCH 7/7] Remove references to historical PRs Co-authored-by: Albert Steppi <1953382+steppi@users.noreply.github.com> --- jupyterlite_sphinx/_try_examples.py | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/jupyterlite_sphinx/_try_examples.py b/jupyterlite_sphinx/_try_examples.py index 4a2b1067..deb4f4dc 100755 --- a/jupyterlite_sphinx/_try_examples.py +++ b/jupyterlite_sphinx/_try_examples.py @@ -315,12 +315,8 @@ def _process_literal_blocks(md_text): + [r"\!\! processed by numpydoc \!\!"] # Attributes section sometimes has no directive. + [r":Attributes:"] - # The See Also section is also a heading that needs to be escaped. This - # showed up in the SymPy documentation which used an older version of - # numpydoc that did not enforce ordering, and modern numpydoc did, hence - # it was not noticed. For future reference, see: - # https://github.com/jupyterlite/jupyterlite-sphinx/pull/251 - # https://github.com/sympy/sympy/pull/27419 + # See Also sections are mapped to Sphinx's `.. seealso::` directive, + # not admonitions or rubrics. + [r"\.\. seealso::"] ) )