Automation of stub generation

[ntoll]

This issue fell out of #1 (cc/ @Josverl).

Currently the stubs for PyScript and MicroPython are a mixture of auto-generated with some hand copy/pasting.

This issue is for discussion about how to move forward with the stub-related aspects of keeping things automatically up-to-date.

For context and as an example of a similar process, we use mkdocs for the PyScript docs and these are automatically versioned and re-published when there's a new release. It'd be great if we could do something similar for the stubs.

For the sake of simplicity, I suggest that in the first instance we limit the scope of our work to simply re-generating the stubs on demand. Further integration into the wider PyScript "estate" (e.g. perhaps using the stubs to auto-generate API documentation for the docs.pyscript.net website, or some other similar sort of integration) can come later.

There are, of course, two aspects to this: stubs for PyScript and stubs relating to MicroPython's WASM build. Furthermore, aspects of PyScript come from the underlying PolyScript project.

For further context of the current state of affairs, here's what @Josverl explained about how he created his recent PR:

@ntoll asked:

Please tell me you have some sort of script to do the extraction of these files from our source code??? 😉 I know of tools like stubgen and others that do this.

@Josverl responded:

Yes, but not from source, but at runtime.
Mostly follows the same automation process as the rest of the stubs, but with some changes due to unique capabilities and inabilities due to the browser environment.
I did my best to design the tooling to be capable to be run in CI, but HIL , wasm in the loop, does have challenges to solve for each port.

• https://micropython-stubber.readthedocs.io/en/main/
• https://github.com/Josverl/micropython-stubber/blob/main/webassembly-stubber%2Freadme.md

Wrt to the integration of the documentation --> Docstrings. Im afraid that currently that is manual copy/paste+Edit. For micropyton i have hand coded a parser for rst to create Docstrings/ docstubs , but as you documentation is in .md, formatted differently that parser is no good for pyscript.
Any .py modules indeed get processed via stubgen, and a few postprocessing steps to undo some issues.

The .Js reflected modules required a seperate approach as they (mostly) don't surface as Python constructable classes, but as instances. With a lot of inheritance.
I wrote a one off script to create stubs from the instances, then used some vscode+regex-foo to simplify the classifieds and add inheritance.
This could be mostly scripted.

I think a relevant question before diving deeply into tooling is whether to:

• generate stubs from documentation
• or API documentation from stubs
• mix or separate functional and API Docs

Each has pros and cons, but I am in favor of maintaining the stubs, automated where possible, and maintain functional docs directly in the publishing format, with crossrefs between them.
But that is not the only way, and some of the tooling will differ based on the process you aim to implement

From the generating documentation from stubs there are several tools to either .MD or .RST

Thoughts, ideas and constructive critique most welcome..! 🤗

[WebReflection]

imho for PyScript we should care about our own namespace and nothing else because everything else is either MicroPython or Pyodide and it's nearly impossible to tell the IDE which one is used, except narrowing down via try/catches but even then, it's possible MicroPython will implement something in the future so that such attempt might not tell the IDE which variant of Python we are using ... we could use directives such as:

# @mpy

# ... or ...

# @py

to disambiguate top level if it's py (default, imho) or mpy code but I don't have many other ideas, I am afraid.

[Josverl]

imho for PyScript we should care about our own namespace and nothing else

Fully agree, the rest is either MicroPython or CPython's scope

There is no need to cater to IDEs,
And static type checking only allows for very very simple conditionals.
But platform is one of them

[ntoll]

Yes, agreed. Looking after the scope of the pyscript namespace would significantly reduce the complexity of this task. 👍

I think we're on the same page here, and we just need to clarify/refine what happens next.

[Josverl]

what is the process and steps that generate the docs today?
Is API.md manually maintained or generated from source comments?