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

Prototype system for publishing templates of package documentation

    Details

      Description

      With DMTN-030 we have a conceptual design for Science Pipelines package documentation design. I've realized part of that concept in pipe_base documentation (DM-1253). The next step is to document these content patterns and the Git repository layout more precisely so that the pipe_base documentation effort can be replicated by anyone in any other package.

      I think we want to continue to use the lsst/templates repository for this type of package documentation. Two key issues with lsst/templates are:

      1. It's filled with non-essential content (like a pybind11 example)
      2. It's hard in that example format to document libraries of repeatable content snippets, like Task documentation pages, for example, that aren't essential parts of a package, but are nontheless standardized.

      This ticket is intended to prototype a new organization of the lsst/templates repository that allows more effective documentation of both package structure and documentation templates.

      Some design goals are:

      • Eventual compatibility with cookiecutter.
      • Ability to document repeating content fragments in a way where an original source of truth is clear, and that templated information is propagated throughout the template project.
      • Ability to have template documentation alongside the template itself.

      On a practical level, Simon Krughoff notes that obs_test is probably a more up-to-date example of a package than the lsst/templates repository is.

        Attachments

          Issue Links

            Activity

            Hide
            tjenness Tim Jenness added a comment -

            DM-8560 – could do it today since everything works, although some people get squeamish at the thought of relying on software that is being called an "alpha release". I have no idea what the timescale is for the final v3.0 release of SCons.

            Show
            tjenness Tim Jenness added a comment - DM-8560 – could do it today since everything works, although some people get squeamish at the thought of relying on software that is being called an "alpha release". I have no idea what the timescale is for the final v3.0 release of SCons.
            Hide
            krughoff Simon Krughoff added a comment -

            O.K. I'm happy. John Swinbank can weigh in and marked reviewed when he is happy.

            Show
            krughoff Simon Krughoff added a comment - O.K. I'm happy. John Swinbank can weigh in and marked reviewed when he is happy.
            Hide
            jsick Jonathan Sick added a comment -

            Pinging John Swinbank. Although I think that since Simon Krughoff went through it we're probably covered review-wise.

            Show
            jsick Jonathan Sick added a comment - Pinging John Swinbank . Although I think that since Simon Krughoff went through it we're probably covered review-wise.
            Hide
            swinbank John Swinbank added a comment -

            I think this is basically fine. I'm a wee bit worried about the added complexity — we've gone from "take this file here and fill in the blanks" to worrying about Jinjas and build systems and cookies and all sorts, and I'm not totally convinced that it's really buying us much — but the new layout is generally saner & clearer than the old one, so I think this can go ahead.

            Show
            swinbank John Swinbank added a comment - I think this is basically fine. I'm a wee bit worried about the added complexity — we've gone from "take this file here and fill in the blanks" to worrying about Jinjas and build systems and cookies and all sorts, and I'm not totally convinced that it's really buying us much — but the new layout is generally saner & clearer than the old one, so I think this can go ahead.
            Hide
            jsick Jonathan Sick added a comment -

            See DM-11699 for the next step, the example auto-build system.

            Show
            jsick Jonathan Sick added a comment - See DM-11699 for the next step, the example auto-build system.

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                jsick Jonathan Sick
                Reviewers:
                John Swinbank
                Watchers:
                John Swinbank, Jonathan Sick, Simon Krughoff, Tim Jenness
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel