(Various modules) Malformed docstrings

[Zach Pearson]

While looking at what it would take to tackle this ticket ​https://www.rbvi.ucsf.edu/trac/ChimeraX/ticket/782 I started looking at the warnings thrown by the build system when creating the documentation. If you've reinstalled the list_info and ui bundles lately, you might notice they're gone!

I find myself using the developer documentation and occasionally see some docstrings that are poorly formatted. If I look at the code the reason is often that they're using Google or NumPy style docstrings or have a strange space between the parameter name and the parameter description, with a unified parameter list that doesn't convert properly when Sphinx reads the file. There's an extension for that:

​https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

which lets those docstrings be read and converted to the usual verbose docstrings without input on our part. The additional benefit is that in future docstrings, it lets us be less verbose and still get good documentation.

Second, I'm always writing code with type hints and I don't think it's good to have to repeat the type in the docstring for it to be picked up by Sphinx. I also don't really like the giant signature that gets generated online by default; the spacing is weird.

Adding this extension:

​https://github.com/agronholm/sphinx-autodoc-typehints

Results in much better looking output.

I don't think it's necessary to turn it into a big project. Probably enabling these two packages and working as normal, the problem will eventually solve itself.

[Zach Pearson]

Original example documentation

[Zach Pearson]

Original docstrings

[Zach Pearson]

Docstrings with type-hinted function signature, and removing the space after the parameter to the class constructor

[Zach Pearson]

Ugly output after adding type hints and removing the space between the constructor parameter and colon

[Zach Pearson]

Docstrings after enabling just the Napoleon extension; the constructor's documentation is fixed but create_child_window still looks bad

[Zach Pearson]

Docstrings after enabling sphinx.ext.napoleon and sphinx_autodoc_typehints