Fix Version/s: None
Component/s: Stack Documentation and UX
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:
- It's filled with non-essential content (like a pybind11 example)
- 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.
- is triggered by
RFC-376 New organization for the templates repository
- is triggering
DM-11699 Create a example auto-build system for the templates repository
- relates to
DM-12674 Revert Sphinx additions to stack package template repos (until production-ready)
DM-12687 Add stack_package cookiecutter template
DM-7097 Develop README, CONTRIBUTING templates for stack packages
- Won't Fix
DM-7198 Document template for EUPS Stack packages in developer guide
O.K. I'm happy. John Swinbank can weigh in and marked reviewed when he is happy.
Pinging John Swinbank. Although I think that since Simon Krughoff went through it we're probably covered review-wise.
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.
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.