RFC-214 now permits Numpydoc docstrings, but a large scale transformation of existing doxygen-formatted docstrings has not yet occurred. This ticket is to create a tool that can be run by developers on their Stack packages to accomplish a first-order transformation from doxygen to numpydoc-formatted docstrings. See https://developer.lsst.io/docs/py_docs.html for an authoritative description of the numpydoc format.
Specifications for the tool:
- Should be standalone, something that a developer can install and use local. Like autopep8.
- Should modify docstrings in situ on a locally-cloned package. It doesn't need to create GitHub PRs or branches or commit changes. Just change Python source files.
- Might be effective to use the XML produced by doxygen to obviate needing to write a doxygen docstring parser. The parsed information in this XML should be sufficient to fill in a template of the short summary, parameters and returns fields.
- Stretch goal: implement a bare docstring template for methods/functions that do not yet have docstrings based on the parameters and existence of a returned or yielded variable.
- There's an understanding that this won't fix the quality of the docstrings and that a developer will still need to go through and improve the content (things like using an imperative form for function summaries).