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

Document pipe_drivers

    Details

    • Type: Story
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: ctrl_pool, pipe_drivers
    • Labels:
      None

      Description

      Please provide a minimal level of documentation for pipe_drivers, to include:

      • A doc directory with the usual content so that docstrings get generated by Doxygen;
      • A package overview;
      • All docstrings should be appropriate for parsing by Doxygen (ie, should start with """! where necessary).

        Attachments

          Issue Links

            Activity

            Hide
            price Paul Price added a comment -

            Thanks, all!

            Merged to master.

            Show
            price Paul Price added a comment - Thanks, all! Merged to master.
            Hide
            rowen Russell Owen added a comment -

            I took a brief look and this is a huge improvement. There are details I'm still unclear on, e.g. why a user would use this code instead of some other ctrl package, but the most important information is present. Thank you for doing this.

            Show
            rowen Russell Owen added a comment - I took a brief look and this is a huge improvement. There are details I'm still unclear on, e.g. why a user would use this code instead of some other ctrl package, but the most important information is present. Thank you for doing this.
            Hide
            tjenness Tim Jenness added a comment -

            This looks fine with me. Russell Owen has agreed to take over the review to give additional input.

            Show
            tjenness Tim Jenness added a comment - This looks fine with me. Russell Owen has agreed to take over the review to give additional input.
            Hide
            price Paul Price added a comment -

            I think I'm now doing the right thing to link to ctrl_pool, but it's not working (can't find the reference); maybe it needs to run in a different environment? I take comfort by the fact that I'm doing the same thing in pipe_tasks used to refer to links in pipe_base, and they don't appear to work there either. I pushed a fixup commit.

            In the process, I discovered that ctrl_pool didn't have any "minimal documentation", so I added some there too. Would you mind having a look at that as well, please Tim Jenness?

            pprice@tiger-sumire:~/LSST/ctrl/pool (tickets/DM-5837=) $ git sub
            commit 6345816c15317c69f39fe4764a51d989f5f8b365
            Author: Paul Price <price@astro.princeton.edu>
            Date:   Mon May 9 15:31:44 2016 -0400
             
                add package overview in doxygen
             
             doc/SConscript      |  3 +++
             doc/doxygen.conf.in |  1 +
             doc/main.dox        | 18 ++++++++++++++++++
             ups/ctrl_pool.cfg   |  2 +-
             4 files changed, 23 insertions(+), 1 deletion(-)
             
            commit a52e8f5fd3794a9c3cd7d4087070a7baee06f1dd
            Author: Paul Price <price@astro.princeton.edu>
            Date:   Mon May 9 15:32:00 2016 -0400
             
                clean up docstrings
             
             python/lsst/ctrl/pool/parallel.py | 16 +++++++++-------
             python/lsst/ctrl/pool/pool.py     | 22 +++++++++++++---------
             2 files changed, 22 insertions(+), 16 deletions(-)
             
            commit 7de2ccd8a726c7cb99f708c8da448018586331b1
            Author: Paul Price <price@astro.princeton.edu>
            Date:   Mon May 9 16:20:55 2016 -0400
             
                add generated doc files to .gitignore
             
             .gitignore | 4 ++++
             1 file changed, 4 insertions(+)
            

            Show
            price Paul Price added a comment - I think I'm now doing the right thing to link to ctrl_pool, but it's not working (can't find the reference); maybe it needs to run in a different environment? I take comfort by the fact that I'm doing the same thing in pipe_tasks used to refer to links in pipe_base, and they don't appear to work there either. I pushed a fixup commit. In the process, I discovered that ctrl_pool didn't have any "minimal documentation", so I added some there too. Would you mind having a look at that as well, please Tim Jenness ? pprice@tiger-sumire:~/LSST/ctrl/pool (tickets/DM-5837=) $ git sub commit 6345816c15317c69f39fe4764a51d989f5f8b365 Author: Paul Price <price@astro.princeton.edu> Date: Mon May 9 15:31:44 2016 -0400   add package overview in doxygen   doc/SConscript | 3 +++ doc/doxygen.conf.in | 1 + doc/main.dox | 18 ++++++++++++++++++ ups/ctrl_pool.cfg | 2 +- 4 files changed, 23 insertions(+), 1 deletion(-)   commit a52e8f5fd3794a9c3cd7d4087070a7baee06f1dd Author: Paul Price <price@astro.princeton.edu> Date: Mon May 9 15:32:00 2016 -0400   clean up docstrings   python/lsst/ctrl/pool/parallel.py | 16 +++++++++------- python/lsst/ctrl/pool/pool.py | 22 +++++++++++++--------- 2 files changed, 22 insertions(+), 16 deletions(-)   commit 7de2ccd8a726c7cb99f708c8da448018586331b1 Author: Paul Price <price@astro.princeton.edu> Date: Mon May 9 16:20:55 2016 -0400   add generated doc files to .gitignore   .gitignore | 4 ++++ 1 file changed, 4 insertions(+)
            Hide
            price Paul Price added a comment - - edited

            Attached pipe_drivers_docs.tar.gz: tarball of compiled doxygen. Have a look at html/index.html .

            I'll look into how to link to ctrl_pool.

            Show
            price Paul Price added a comment - - edited Attached pipe_drivers_docs.tar.gz: tarball of compiled doxygen. Have a look at html/index.html . I'll look into how to link to ctrl_pool.
            Hide
            tjenness Tim Jenness added a comment -

            Looks like it meets the minimum requirement. Can I see a rendered version somewhere on the doxygen server? (I can never find the URL for the LSST documents). In main.dox is it possible for mentions of other packages to be links to the docs of those other packages?

            Show
            tjenness Tim Jenness added a comment - Looks like it meets the minimum requirement. Can I see a rendered version somewhere on the doxygen server? (I can never find the URL for the LSST documents). In main.dox is it possible for mentions of other packages to be links to the docs of those other packages?
            Hide
            price Paul Price added a comment -

            Is this sufficient, Tim Jenness?

            price@price-laptop:~/LSST/pipe/drivers (tickets/DM-5837=) $ git sub
            commit e04d57d6819afcd4dc1a75cc0d66439f36271319
            Author: Paul Price <price@astro.princeton.edu>
            Date:   Mon May 9 14:50:37 2016 -0400
             
                add package overview in doxygen
             
             doc/SConscript      |  3 +++
             doc/doxygen.conf.in |  1 +
             doc/main.dox        | 20 ++++++++++++++++++++
             3 files changed, 24 insertions(+)
             
            commit 940e8af26763a6e36ba14ed76fdc13fa4e7a9e9e
            Author: Paul Price <price@astro.princeton.edu>
            Date:   Mon May 9 15:05:19 2016 -0400
             
                clean up docstrings
             
             python/lsst/pipe/drivers/coaddDriver.py     | 36 +++++++++++++++------
             python/lsst/pipe/drivers/constructCalibs.py |  2 +-
             python/lsst/pipe/drivers/multiBandDriver.py | 49 ++++++++++++++++++-----------
             python/lsst/pipe/drivers/utils.py           |  2 ++
             4 files changed, 59 insertions(+), 30 deletions(-)
            

            Show
            price Paul Price added a comment - Is this sufficient, Tim Jenness ? price@price-laptop:~/LSST/pipe/drivers (tickets/DM-5837=) $ git sub commit e04d57d6819afcd4dc1a75cc0d66439f36271319 Author: Paul Price <price@astro.princeton.edu> Date: Mon May 9 14:50:37 2016 -0400   add package overview in doxygen   doc/SConscript | 3 +++ doc/doxygen.conf.in | 1 + doc/main.dox | 20 ++++++++++++++++++++ 3 files changed, 24 insertions(+)   commit 940e8af26763a6e36ba14ed76fdc13fa4e7a9e9e Author: Paul Price <price@astro.princeton.edu> Date: Mon May 9 15:05:19 2016 -0400   clean up docstrings   python/lsst/pipe/drivers/coaddDriver.py | 36 +++++++++++++++------ python/lsst/pipe/drivers/constructCalibs.py | 2 +- python/lsst/pipe/drivers/multiBandDriver.py | 49 ++++++++++++++++++----------- python/lsst/pipe/drivers/utils.py | 2 ++ 4 files changed, 59 insertions(+), 30 deletions(-)

              People

              • Assignee:
                price Paul Price
                Reporter:
                nlust Nate Lust
                Reviewers:
                Russell Owen, Tim Jenness
                Watchers:
                Nate Lust, Paul Price, Russell Owen, Tim Jenness
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel