Skip to content
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.

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

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

Merged
merged 3 commits into from
Feb 12, 2025

Conversation

steppi
Copy link
Collaborator

@steppi steppi commented Jan 27, 2025

Closes #256

This PR updates the list of section header patterns for determining the next section after the examples section to a list which should work for sphinx.ext.napoleon. It also updates the list of possible numpydoc section patterns for correctness. The latter doesn't really matter that much though. Recent versions of numpydoc are opinionated and will re-arrange headers to fit a preferred order, so most of these patterns will never be found after an examples section after preprocessing by numpydoc. It wasn't much extra work to include the correct pattern for all headings though.

The core idea here is that sphinx.ext.napoleon and numpydoc each map human writable headers like

Examples
--------------

to directives and other forms of rst markup, and there are some differences in what they can output for different section headers, but this wasn't accounted for because I had only tested global_enable_try_examples with numpydoc. sphinx.ext.napoleon is also widely used though (e.g. Astropy, IPython, XArray) and should be supported.

@steppi steppi added the bug Something isn't working label Jan 27, 2025
Copy link
Member

@agriyakhetarpal agriyakhetarpal left a comment

Choose a reason for hiding this comment

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

Thanks, @steppi! I have a suggestion and a question based on our original plan for what contents are to be included. Also, I think it would be nice to link a "Kitchen Sink" sort of page in our docs with the TryExamples directive, containing all the relevant options from your toy/test website that you mentioned earlier in our meeting, even if it's not added to an index anywhere and stays as an orphan page, so that we can see on further PRs that change these files that might that things remain working – considering that we virtually have no tests.

Also, the tests are failing, I think we ought to add black as a pre-commit hook instead soon

jupyterlite_sphinx/_try_examples.py Outdated Show resolved Hide resolved
jupyterlite_sphinx/_try_examples.py Show resolved Hide resolved
steppi and others added 2 commits January 27, 2025 20:17
Co-authored-by: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
@steppi
Copy link
Collaborator Author

steppi commented Jan 28, 2025

Thanks @agriyakhetarpal!

Copy link
Member

@agriyakhetarpal agriyakhetarpal left a comment

Choose a reason for hiding this comment

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

Thanks, @steppi!

jupyterlite_sphinx/_try_examples.py Show resolved Hide resolved
@agriyakhetarpal
Copy link
Member

I would like to merge this for now so that it can unblock further work on the related issues and reduce conflicts with my work to make notebook modifications more generic. We can work on other improvements before the release in case we might have missed anything. Thanks for improving this area of the code, @steppi!

@agriyakhetarpal agriyakhetarpal merged commit 7702294 into jupyterlite:main Feb 12, 2025
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Correctly delimiting the examples section when using sphinx.ext.napoleon instead of numpydoc
2 participants