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

Add multiline example to Struct

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: dm_dev_guide
    • Labels:
      None

      Description

      Per review discussion in DM-16017, the description of a `Struct`'s fields should be indented to the level of the field name. However, this is not clear from the example in the python style guide (where all the field descriptions fit on one line), nor from the rest of the guide (which uses different indentation styles in different contexts).

      Add a long description to the example so that the policy is clearly documented.

        Attachments

          Issue Links

          is triggered by

          RFC - An issue whose primary purpose is to advertise an intent and allow stakeholders to comment. RFC-559 Revised Numpydoc guidelines for Parameters, Returns & Yields sections

          • Implemented
          relates to

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-16017 Prototype a metrics-handling Task

          • Done

            Activity

            Ascending order - Click to sort in descending order
            Hide
            Permalink
            jsick Jonathan Sick added a comment -

            I'd like to do this ticket since I'm already doing DM-16826, and would further like to change the style from a reStructuredText list to a reStructuredText definition list.

            Show
            jsick Jonathan Sick added a comment - I'd like to do this ticket since I'm already doing DM-16826 , and would further like to change the style from a reStructuredText list to a reStructuredText definition list.
            Hide
            Permalink
            jsick Jonathan Sick added a comment -

            By the way, the syntax we're currently using for Struct and dict fields are elementary reStructuredText lists, documented here: https://developer.lsst.io/restructuredtext/style.html#lists

            Show
            jsick Jonathan Sick added a comment - By the way, the syntax we're currently using for Struct and dict fields are elementary reStructuredText lists, documented here: https://developer.lsst.io/restructuredtext/style.html#lists
            Hide
            Permalink
            krzys Krzysztof Findeisen added a comment -

            Go right ahead. Definition list sounds like a great idea.

            Show
            krzys Krzysztof Findeisen added a comment - Go right ahead. Definition list sounds like a great idea.
            Hide
            Permalink
            jsick Jonathan Sick added a comment -

            Great, thanks.

            Show
            jsick Jonathan Sick added a comment - Great, thanks.
            Hide
            Permalink
            jsick Jonathan Sick added a comment -

            This PR reflects RFC-559. See the PR for links to specific parts of the documentation that have been updated.

            Show
            jsick Jonathan Sick added a comment - This PR reflects RFC-559 . See the PR for links to specific parts of the documentation that have been updated.
            Hide
            Permalink
            ktl Kian-Tat Lim added a comment -

            A couple of minor suggestions. I approve this change.

            Show
            ktl Kian-Tat Lim added a comment - A couple of minor suggestions. I approve this change.
            Hide
            Permalink
            jsick Jonathan Sick added a comment -

            Good points; I've addressed your suggestions. Thanks!

            Show
            jsick Jonathan Sick added a comment - Good points; I've addressed your suggestions. Thanks!

              People

              Assignee:
              jsick Jonathan Sick
              Reporter:
              krzys Krzysztof Findeisen
              Reviewers:
              Kian-Tat Lim
              Watchers:
              Jonathan Sick, Kian-Tat Lim, Krzysztof Findeisen
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Jenkins

                  No builds found.