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

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

    Details

      Description

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

        Attachments

          Issue Links

            Activity

            There are no comments yet on this issue.

              People

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

                Dates

                • Created:
                  Updated:

                  Summary Panel