(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

[Tom Goddard]

Would be great to have improved format programmer documentation. I see differences when argument type specifiers are present, but we don't use those much (so far). So I am more interested in what other format changes you propose. Let's discuss at next week's developer meeting. We will need to have examples to look at so if you (Zach) could screen share some examples during the meeting and explain the advantages that would be good.

Thanks for fixing up the doc parsing errors. I have done that many times in the past but new ones are always cropping up.

Our programmer doc strings use a variety of different formats in the doc strings producing different formats in the online docs and it would be good if we stuck with one style.

[Zach Pearson]

Disabling numpydoc and enabling napoleon resulted in a handful of new formatting warnings that had to be corrected, but they weren't that difficult. Checked a few pages to ensure they looked normal then enabled sphinx_autodoc_typehints and didn't find any breakages. I think I can say with relative confidence that any formatting issues that have yet to be discovered are not due to napoleon/sphinx_autodoc_typehints.

[Zach Pearson]

Merged sphinx_napoleon_typehints into develop.