Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-214

Use numpydoc and reStructuredText for Python docstrings

    Details

    • Type: RFC
    • Status: Implemented
    • Resolution: Done
    • Component/s: DM
    • Labels:
      None

      Description

      We'll soon (~1-2 months) have a documentation system that renders HTML documentation from Python docstrings written with reStructuredText.

      At one of the PCW hack sessions (with a large majority of non-DMLT DM members in attendance) we had unanimous agreement that we should start writing Python docstrings in this form now, instead of prefixing docstrings with a "!" to invoke Doxygen markup.

      This will temporarily make HTML documentation for Python uglier (it will be rendered as reStructuredText source), but will eventually make it nicer, and it will make on-line Python docstrings modestly more readable (because reStructuredText source is more readable than Doxygen markup).

      If other hack session work goes quickly and this RFC is accepted ahead of schedule, this could give us an opportunity to start this transition for existing code during the meeting.

        Attachments

          Container Issues

            Issue Links

              Activity

                People

                • Assignee:
                  jbosch Jim Bosch
                  Reporter:
                  jbosch Jim Bosch
                  Watchers:
                  Cindy Wang [X] (Inactive), David Shupe, Jim Bosch, John Parejko, John Swinbank, Jonathan Sick, Kian-Tat Lim, Pim Schellart [X] (Inactive), Robert Lupton, Russell Owen, Tim Jenness, Xiuqin Wu
                • Votes:
                  1 Vote for this issue
                  Watchers:
                  12 Start watching this issue

                  Dates

                  • Created:
                    Updated:
                    Resolved:
                    Planned End:

                    Summary Panel