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

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

    XMLWordPrintable

    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

            Hide
            jsick Jonathan Sick added a comment -

            No longer relevant.

            Show
            jsick Jonathan Sick added a comment - No longer relevant.

              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:
                Resolved:

                  Jenkins Builds

                  No builds found.