Skip to content

Correctly handle case where "See Also" section follows "Examples" in global_enable_try_examples #251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jan 13, 2025
Merged

Correctly handle case where "See Also" section follows "Examples" in global_enable_try_examples #251

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
f24cd2d
Add `..seealso` section as a pattern
agriyakhetarpal Jan 10, 2025
10abc82
Fix escaping of regex characters
agriyakhetarpal Jan 11, 2025
5f187f3
Reword comment about SymPy's special case
agriyakhetarpal Jan 12, 2025
79e864e
Add subset of docutils + Sphinx directives to end at
agriyakhetarpal Jan 13, 2025
08e70bd
Revert "Add subset of docutils + Sphinx directives to end at"
agriyakhetarpal Jan 13, 2025
5397180
Reword comment about "See Also" section
agriyakhetarpal Jan 13, 2025
631dfeb
Remove references to historical PRs
agriyakhetarpal Jan 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion jupyterlite_sphinx/_try_examples.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -303,18 +303,44 @@ 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",
Copy link
Collaborator

@steppi steppi Jan 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some of these like "pull-quote" and "parsed-literal" seem like they would be reasonable to put in an examples section. Others would be very strange to put in the middle of an examples section when using numpydoc. I made it so that the next section had to be a numpydoc section header because I kept running into new directives that were used in the middle of examples sections. Rather than using other directives as a delimiter, what I did was map them to markdown so they appear in the notebooks (math, literal blocks, reference), or ignore them so they don't appear in notebooks (plot, only).

The intention was only to support numpydoc (and sphinx.ext.napoleon because it is compatible) and this is clearly documented. Are there reasonable uses of numpydoc that are not currently supported? I think it's pretty reasonable to say, "if you're using global_enable_try_examples, then an example section is until the next numpydoc section header or the end of the docstring, if you want to delimit the section differently, manually insert the try_examples directive". If there are directives which can be used examples section which aren't currently being handled, by either mapping them into the notebooks or ignoring them in the notebooks, then that is something that should be fixed, but perhaps effort should only be spent on any particular case if we see it in the wild.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, here's what I propose. ignore_directives should be changed to explicit_ignore_directives. If any directive appears in an examples section which is not in explicit_ignore_directives or not mapped to markdown in some way, it should be implicity ignored, but there should be an informative warning.

]

_examples_start_pattern = re.compile(r".. (rubric|admonition):: Examples")
_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.
+ [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]
)
)

Expand Down
Loading