ipywidgets

ipywidgets copied to clipboard

Problem

There is no easy way to see all the methods available to widget objects. This is true for both the Python and ts sides. This is makes it tricky to learn how to make a custom widget.

Suggested Improvement

1. Use sphinx autodoc/autosummary etc to add a Python methods page to the documentation
2. Use typedoc or equivalent to document the available frontend methods.\

+1 for this idea. I was currently looking at the arguments of Video here: https://ipywidgets.readthedocs.io/en/latest/search.html?q=Video but could not find any info, but I discovered the docstings in GitHub search: https://github.com/jupyter-widgets/ipywidgets/blob/e0d41f6f02324596a282bc9e4650fd7ba63c0004/ipywidgets/widgets/widget_media.py#L168

pythreejs has some examples of raising the bar on trait-related auto documentation:

Getting that out of there, and expanding it to an installable sphinxext-traitlets would help a lot.

Also, likely on 8.x, we should consider going 3.7+ and using type hints all over, such that sphinx-autodoc-typehints could provide the "real," non-descriptor that IDEs/static analysis tools would actually use.

On the typedoc front: yeah, it's there, and relatively easy to pipe it out to markdown, and then include that with e.g. myst-nb.

As an alternative, it may be worth considering sphinx-js. pyodide uses it, and would have the advantage of better enabling links between the language domains, which seems kinda important.

Additionally the existing schema could be documented with e.g. sphinx-jsonschema.

+1 on this, I kept looking for the actual RTD reference, and found this issue instead. This package seems to be really well documented, so I think it would be relatively simple to get Sphinx autodoc to work with the existing codebase. It handles inheritance without issue.

I hope that this issue hasn't been forgotten, because it would really take this up a significant notch in terms of usability!