Use sphinx to render docstring in contextual help

[ericpre]

Problem

Rendering docstring using the numpydoc formatting could be significantly better using sphinx. For example, spyder "Help" panel is more readable particularly when the docstring contain latex. This should be useful to render cross-referencing to python objects.

For example, the contextual help of:

import sympy
sympy.atan2

Jupyter lab contextual help:

Spyder help panel:

Proposed Solution

Use sphinx to render contextual help.

Additional context

See for example spyder help panel: https://docs.spyder-ide.org/help.html#understanding-help-modes

[mbellitti]

Is there any progress on this? I tried using docrepr as explained here, but the results are not very consistent (sometimes it shows a function's source rather than the rendered docstring), and it looks docrepr was last updated almost two years ago.

Rendering the docstring in the same way Spyder does it would be a significant quality of life improvement. I'm happy to help, is there something I can do?

[joelostblom]

I would love to have this as well and think it would be really helpful, especially for novices learning JupyterLab. Some related issues/projects that might be helpful are:

• Math not rendering in parameter hints #4403
• Only top level headings are rendered richly spyder-ide/docrepr#57
• Make available for jupyterlab regardless of which kernel is used for a specific notebook spyder-ide/docrepr#55
• Use in JupyterLab currently?  python-lsp/docstring-to-markdown#25

[mbellitti]

Thank you for the links. I saw someone mention writing a server extension, do you know if there's any project like that being developed?

[joelostblom]

Hmm, I am not aware of any at the moment

[krassowski]

Well, there is https://github.com/jupyter/papyri and https://github.com/carreau/papyri-lab - it does not hook into the context help renderer yet it seems but it would certainly be possible.

[joelostblom]

Wow that's cool, I had totally missed that this was in development. Thank you @Carreau for working on it, I really enjoyed reading your blog post as well!

[krassowski]

New thing https://github.com/krassowski/ipython-markdown-inspector makes IPython return Markdown-formatted docstrings. It requires IPython 8.21 and will be even better with 8.22 (once released).