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

Use numpydoc and reStructuredText for Python docstrings

    XMLWordPrintable

    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

          Issue Links

            Activity

            jbosch Jim Bosch created issue -
            pschella Pim Schellart [X] (Inactive) made changes -
            Field Original Value New Value
            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.
            {color:#14892c}colored text{color}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.
            pschella Pim Schellart [X] (Inactive) made changes -
            Description {color:#14892c}colored text{color}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.
            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.
            jbosch Jim Bosch made changes -
            Link This issue relates to DM-7345 [ DM-7345 ]
            jbosch Jim Bosch made changes -
            Resolution Done [ 10000 ]
            Status Proposed [ 10805 ] Adopted [ 10806 ]
            tjenness Tim Jenness made changes -
            Link This issue is triggering DM-7345 [ DM-7345 ]
            tjenness Tim Jenness made changes -
            Link This issue relates to DM-7345 [ DM-7345 ]
            jsick Jonathan Sick made changes -
            Link This issue is triggering DM-5456 [ DM-5456 ]
            jsick Jonathan Sick made changes -
            Status Adopted [ 10806 ] Implemented [ 11105 ]

              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 [X] (Inactive)
              Votes:
              1 Vote for this issue
              Watchers:
              12 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:
                Planned End:

                  Jenkins Builds

                  No builds found.