Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-9015

Create tool to semi-automatically migrate Python docstrings to Numpydoc format



      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).


          Issue Links


            There are no comments yet on this issue.


              • Assignee:
                jsick Jonathan Sick
                jsick Jonathan Sick
                Jonathan Sick
              • Votes:
                0 Vote for this issue
                1 Start watching this issue


                • Created:

                  Summary Panel