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

Better documentation for ap_verify

    Details

    • Story Points:
      4
    • Sprint:
      Alert Production F17 - 9, Alert Production F17 - 10, Alert Production F17 - 11, AP S18-1
    • Team:
      Alert Production

      Description

      The current documentation for ap_verify consists of a readme file and some unpublished API documentation. The readme has basic usage instructions, but assumes the user will run ap_verify -h to learn the details of each command line argument.

      We should move documentation out of the readme and into well-organized user-facing documents. This work may need to wait until Jonathan Sick's documentation upgrades roll out.

        Attachments

          Issue Links

            Activity

            Hide
            jsick Jonathan Sick added a comment -

            If you follow the structure of pipe_base, you should be fine. It's possible to do single-package builds, so there shouldn't be a need to integrate with pipelines_lsst_io initially. When you begin, ping me and I'll send instructions with the documentation build environment. I also expect a Jenkins job for Pipelines documentation to be available sometime in October.

            Show
            jsick Jonathan Sick added a comment - If you follow the structure of pipe_base , you should be fine. It's possible to do single-package builds, so there shouldn't be a need to integrate with pipelines_lsst_io initially. When you begin, ping me and I'll send instructions with the documentation build environment. I also expect a Jenkins job for Pipelines documentation to be available sometime in October.
            Hide
            krzys Krzysztof Findeisen added a comment - - edited

            I propose the following documentation structure. Following DMTN-030, I provide only module and package topics in ap_verify, although Datasets should be documented as a framework (tying in ap_verify_dataset_template and implementations like ap_verify_hits2015), and "running ap_verify" might make sense as a processing topic.

            • Module topics
              • lsst.ap.verify
                • Running ap_verify from the command line
                  • Dataset format (link to Dataset framework topic)
                  • Metrics output and use (link to verify documentation)
                  • Cross-reference to ap_pipe?
                • Dataset framework
                  • Implementing a dataset
                  • Relationship between datasets and butler repositories
                • Policy/guarantees on metrics handling and failed runs
                • API Reference? (ap.verify not designed for use as a library, so runApVerify is only public API member)
                  • ap.verify
                  • ap.verify.measurement
            • Package topics
              • lsst-dm/ap_verify package
            Show
            krzys Krzysztof Findeisen added a comment - - edited I propose the following documentation structure. Following DMTN-030, I provide only module and package topics in ap_verify , although Datasets should be documented as a framework (tying in ap_verify_dataset_template and implementations like ap_verify_hits2015 ), and "running ap_verify" might make sense as a processing topic. Module topics lsst.ap.verify Running ap_verify from the command line Dataset format (link to Dataset framework topic) Metrics output and use (link to verify documentation) Cross-reference to ap_pipe ? Dataset framework Implementing a dataset Relationship between datasets and butler repositories Policy/guarantees on metrics handling and failed runs API Reference? ( ap.verify not designed for use as a library, so runApVerify is only public API member) ap.verify ap.verify.measurement Package topics lsst-dm/ap_verify package
            Hide
            krzys Krzysztof Findeisen added a comment -

            The first paragraph (explaining lsst.ap.verify.measurements) of this comment should also be transferred to the documentation.

            Show
            krzys Krzysztof Findeisen added a comment - The first paragraph (explaining lsst.ap.verify.measurements ) of this comment should also be transferred to the documentation.
            Hide
            krzys Krzysztof Findeisen added a comment -

            Hi Eric Bellm, when you get the chance, could you please review the content of the documentation for inaccuracies or conceptual problems? I think I've reproduced ap_verify's current behavior, but I may have overlooked deviations from its desired behavior or misrepresented the motivation behind some design decisions.

            Jonathan Sick, since this is one of the first packages to have new-style documentation, can you review the structure and style for compliance with the new guidelines?

            Show
            krzys Krzysztof Findeisen added a comment - Hi Eric Bellm , when you get the chance, could you please review the content of the documentation for inaccuracies or conceptual problems? I think I've reproduced ap_verify 's current behavior, but I may have overlooked deviations from its desired behavior or misrepresented the motivation behind some design decisions. Jonathan Sick , since this is one of the first packages to have new-style documentation, can you review the structure and style for compliance with the new guidelines?
            Hide
            krzys Krzysztof Findeisen added a comment -

            Eric Bellm, it's ready for re-review.

            Show
            krzys Krzysztof Findeisen added a comment - Eric Bellm , it's ready for re-review.
            Hide
            krzys Krzysztof Findeisen added a comment -

            Thanks for the feedback!

            Show
            krzys Krzysztof Findeisen added a comment - Thanks for the feedback!

              People

              • Assignee:
                krzys Krzysztof Findeisen
                Reporter:
                krzys Krzysztof Findeisen
                Reviewers:
                Eric Bellm, Jonathan Sick
                Watchers:
                Eric Bellm, Jonathan Sick, Krzysztof Findeisen, Meredith Rawls
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel