This announcement is all about templates. First, we’ve got a brand new DM stack package template. And to help you make those new packages, we’ve got a brand new command-line app called
The new stack package template
The new stack package template lives on GitHub: https://github.com/lsst/templates/tree/master/project_templates/stack_package
This is a Cookiecutter template, meaning that you can programmatically create new projects from it — it’s not just a static example to look at. We’ve gone to some lengths to add logic to the templates that reduces, and even eliminates, the amount of work you need to do to start up a new package. Some examples:
- If your package is called
example_subpackage, the template makes the namespace
lsst.example.subpackageand adds an “extra” intermediate
__init__.pyfile in the
python/lsst/exampledirectory. See this example.
- The C++ namespace is also mapped to the package name, like this header file and this source file.
- You can configure the template to create a Python-only package, like this example.
I’ve done my best to incorporate all our latest standards in the template. For example, it features our new license and copyright patterns. It also features Travis CI configuration for flake8 Python linting. Even if you don’t use the template to create a new package (and we shouldn’t be creating lots of new packages!) the intent is to use the examples generated from this template as references when we migrate existing packages to conform to new standards.
If you spot anything amiss in this template, please do let me know with a Jira ticket.
Introducing the templatekit CLI
The new https://github.com/lsst/templates repository is slowly growing, with several file templates, and now the stack package project template. To help you use these templates in your daily workflows, we’ve created the
templatekit command-line app.
templatekit is based on the same tools we use to generate and test the examples in the templates repository.
To get started, clone the templates repository and install the
git clone https://github.com/lsst/templates cd templates pip install .
If you can, I encourage you to install
templatekit in a virtual Python environment. If you don’t know about those, the Python Guide will get you started. You’ll need Python 3 too.
templatekit is installed, you can use it to list templates:
The license preambles sound fun. Try filling in that
stack_license_preamble_py template. Run:
templatekit make stack_license_preamble_py -c
templatekit copies the rendered text to the clipboard so you can easily paste the result into your editor. You can also write the text to a file with the
You can create new projects the same way. For example, create a new stack package:
templatekit make stack_package -o ../
-o option makes sure the stack package is created next to the
templates/ repo, not inside it.)
You can get more information about
templatekit and its commands by running:
Why are we doing all this? What’s next?
I believe that a template is worth a few thousand words of documentation. In fact, templates are documentation. Having accurate templates is a great way for us, as an organization, to adhere to standards that make our products more maintainable. A big reason for doing this now was to help me document how to add new-style documentation to our packages.
One of the next steps for this work is to incorporate content from the templates repository into the Developer Guide. That way, a documentation page talking about the
.travis.yml file in our packages, for example, has the same
.travis.yml as in our templates. A new reStructuredText directive will let us do this.
In the coming weeks and months, I expect the templates repository to grow. I’ll be consolidating our other Cookiecutter templates into that repository. @afausti is talking about adding templates for SQUASH Bokeh apps. @adam is talking about adding Jupyter Notebook templates for the Science Platform. @KSK wants to create a template for new-style obs packages.
We can also expect improvements in the infrastructure around these templates.
templatekit will appear on PyPI and likely Homebrew as well. Sqrbot will also use this tooling to let you create new projects and files from Slack.