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

[agriyakhetarpal]

Problem

From #251 (comment): ensure that numpydoc sections are correctly mapped so that the TryExamples directive correctly generates notebooks.

Proposed Solution

From @steppi on Slack:

• stop at rubric, seealso, admonitions that start can start a section (there are some of the latter)
• convert admonitions to their respective colours and not stop
• ignore the rest of the unhandled directives and see if someone brings one of them up

Additional context

N/A

[steppi]

Thanks @agriyakhetarpal for making this issue. A few clarifications below.

From #251 (comment): ensure that numpydoc sections are correctly mapped so that the TryExamples directive correctly generates notebooks.

You should probably mention that these steps are specifically to make it so TryExamples works with sphinx.ext.napoleon. The current logic works fine for numpydoc, but is less efficient than it could be, because it checks for section headers which couldn't exist after the examples section in a docstring after being processed by numpydoc.

The core issue is that numpydoc enforces an ordering for the section, while sphinx.ext.napoleon doesn't. sphinx.ext.napoleon also allows for custom section header names. The regular expression pattern we have for identifying the start of the next section (or end of the docstring if "Examples" is last), works fine for numpydoc because there is a limited set of things which could appear next and the regular expression pattern being used matches all of them. This regular expression pattern does not correctly match all things which could appear after the "Examples" section when using sphinx.ext.napoleon.

The documentation for TryExamples says it should support sphinx.ext.napoleon, and doing so is not difficult, so it seems reasonable to make these changes.

[steppi]

• convert admonitions to their respective colours and not stop

Currently, admonitions that cannot signal a new section are not used to delimit the examples section. Converting admonitions to their respective colors is a solution for a separate problem: Sphinx directives which can appear inside of an Examples section which are not currently being handled. Currently an admonition inside of an Examples section would lead to a raw Sphinx directive making its way into a markdown cell in the generated notebook.

[agriyakhetarpal]

Thanks for adding the clarifications!

• convert admonitions to their respective colours and not stop

Currently, admonitions that cannot signal a new section are not used to delimit the examples section. Converting admonitions to their respective colors is a solution for a separate problem: Sphinx directives which can appear inside of an Examples section which are not currently being handled. Currently an admonition inside of an Examples section would lead to a raw Sphinx directive making its way into a markdown cell in the generated notebook.

Yes, sorry, I think this point is part of the other issue #254 – I didn't remove it when copy-pasting.