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 templatekit.
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 namespacelsst.example.subpackageand adds an “extra” intermediate__init__.pyfile in thepython/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 templatekit app:
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.
Now that templatekit is installed, you can use it to list templates:
templatekit list
The license preambles sound fun. Try filling in that stack_license_preamble_py template. Run:
templatekit make stack_license_preamble_py -c
Then answer the prompts to fill in the license preamble. Behind the scenes, templatekit uses Cookiecutter. If you have any questions about what the variables are, check out the template’s README.
With the -c (--copy) option, 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 -o (--output) option.
You can create new projects the same way. For example, create a new stack package:
templatekit make stack_package -o ../
(The -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:
templatekit -h
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.