id	summary	reporter	owner	description	type	status	priority	milestone	component	version	resolution	keywords	cc	blockedby	blocking	notify_on_close	platform	project
5120	(Various modules) Malformed docstrings	Zach Pearson	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. "	defect	assigned	low		Documentation								all	ChimeraX