Support for (Python) code documentation like in RST Sphinx

[echarles]

Is there a way/plan to support the generation of Python code documentation like in RST Sphinx?

See example of such generation on https://jupyter-client.readthedocs.io/en/stable/api/modules.html

I guess a call to a subprocess would be possible, but would lack the look&feel coherence.

Another similar question is the support of documentation for other languages like typescript, golang...

[riziles]

non-sequitur: Mozilla actually created a project to autodoc TypeScript (https://github.com/mozilla/sphinx-js), but.... it actually uses Sphinx on the backend. There is also this: https://github.com/jsdoc2md/jsdoc-to-markdown/

[rowanc1]

Our initial focus with mystjs is on scientific publishing, so we don't have near term support for this planned out, however, @Carreau is doing some work on this in another context (papyri) and is looking to the myst-spec as a place to collaborate -- so there is some hope of doing this in the future in a seamless way I think!

For other languages, like typescript, some of them have packages to allow you to export to structured data (or markdown), and from there it is relatively easy to integrate into mystjs/myst-spec. @stevejpurves did a bit of looking into this for Thebe and some of the pointers for that are in #75 - maybe @stevejpurves you can follow up here with what you learned on the typescript side!

[echarles]

@Carreau Any idea/roadmap if papyri could leverage this? https://twitter.com/choldgraf/status/1658728960484683777

[stevejpurves]

Speaking with @Carreau and JupyterCon it seems that papyri is well aligned and could (is moving to) use the myst ast at it's core. So once that's the case we need to look at implementing the custom/additional directives needed in myst-to-react which papyri could then leverage for it's front end, and it myst in turn invokes papyri to build docs pages for inclusion in a myst website. That was my understanding from the convo on the conference floor, but we need to pick apart the details a bit more and do some testing.

[echarles]

This is awesome.

Would a dedicated package myst-papyri be created to implement the connection between those 2 projects? And where?

[Carreau]

I think it might be a bit too early to try to have custom papyri directive, or to use papyri for that, but I'd like to discuss the ability at least for now to render custom nodes – maybe that what you call directive, but in papyri I try to remove the directive fro the ast as much as I can. My main reason being that the same nodes might be generated in different ways.

For example .. code:: and example blocks with >>> some code may result in the same ast and the second one is not a directive.

I opened jupyter-book/myst-spec#61, which is one use case where I'd like a custom node (to experiment).

Papyri is also likely to use griffe to extract function signature, and I'd like a "Signature" node, with for example the end-user option to show (or not), function signature, so I would need a custom renderer.

so far I've tried to call myst.renderMdast(...), and set some option on myst to have custom Hast handler but without success, though I'm not a JS/TS person.

Another reason to have maybe a custom renderer would be to trigger custom JupyterLab javascript when clicking on some links.

We can try to setup a call in a week or two if you want to re-disccuss what is possible/where to go.

[stevejpurves]

yes it we are going to look at integrating these (which we totally should!) we should get together and line up AST wise, as well as look at where dev is needed. We can help getting the parser going on the JS/TS side too.