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

          Container Issues

            Issue Links

              Activity

                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