Clean up docstrings to match Sphinx expectations

[joefowler]

Original report by Joseph Fowler (Bitbucket: joe_fowler, ).

---

The make doctest step that auto-generates documentation is generating 1500+ lines of errors and warnings, and the resulting docs (https://oneilg.bitbucket.io/mass/manual_autodoc.html#mass.LineFitter for example) have spacing that looks pretty stupid. Clearly, we are using Sphinx wrong.

At https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html there’s advice about how to use VS Code to auto-generate a skeleton docstring.

If we are going to auto-generate documentation and deploy it, then we should really use the correct form. This is a huge project! I understand. Perhaps there are tools to help make it easy?

[joefowler]

Original comment by Joseph Fowler (Bitbucket: joe_fowler, ).

---

See the VS Code plugin “autoDocstring” to generate compatible skeletons. I have a branch showing that this seems to work, though it will be a ton of work to fix all the error/warnings. Not sure whether it’s worth it….

[joefowler]

Original comment by Joseph Fowler (Bitbucket: joe_fowler, ).

---

Discussed with @{557058:9524f6a0-ef9f-4466-b913-d04e51ff9093} today. We hate the native Sphinx docstring format, with all the ugly :param and :type clutter that makes a string hard to read in the REPL. We prefer the numpydoc format, which is close to what we were already doing. However! It will require Sphinx to have some kind of Napoleon extension.

• Add this extension
• Try some docstrings in that format. (BTW, you can set up your VS Code autoDocstring package to use numpydoc as its format. That was obviously a requirement here.)

‌

[joefowler]

Original comment by Joseph Fowler (Bitbucket: joe_fowler, ).

---

See https://numpydoc.readthedocs.io/en/latest/format.html for full description of the format.