Rubin technical note repository, based on Markdown and Sphinx.
This template generates a new technical note (technote) repository based on Sphinx. Rubin technotes, in general, let you document technical designs, proposals, product overviews, results of prototyping experiments, and other types of documentation that doesn't fit in either the change-controlled document tree, or in user documentation. See Technotes for stand-alone technical documentation in the Developer Guide.
Keep in mind that technotes are single-page websites.
Specifically, don't use toctree to create a multi-page site.
Technotes are constrained to single pages so that they can be archived to DocuShare, and as a result the technote infrastructure is designed specifically to support a single-page site.
The name of the first author, formatted as First Last.
Once the technote repository is generated you can add additional authors to the authors list in metadata.yaml.
The identifier of the technote series. Choose the series that fits the document's purpose or aligns with the organization creating the document:
DMTNfor Data Management technical notes. See DMTN-000.ITTNfor LSST IT technical notes.RTNfor Rubin Observatory operations technical notes (all departments).PSTNfor Project Science Team technical notes.SMTNfor Simulations Group technical notes. See SMTN-000.SITCOMTNfor Systems Integration, Testing, and Commissioning notes.SQRfor SQuaRE technical notes. See SQR-000.TSTNfor Telescope & Site technical notes.TESTNfor testing the technical system. These notes may be purged at any time.
The serial number. Use three digits padded with zeros. If you are creating a technical note manually with this template, see the Create a technote instructions for how to determine the serial number.
The title of the technote.
The name of the GitHub repository Cookiecutter will automatically format this for you based on the series and serial_number information.
The GitHub organization where this technote resides. Choose a GitHub organization that matches the series:
lsst-dmfor the DM DMTN series.lsst-itfor the ITTN series.rubin-observatoryfor the RTN series.lsst-simsfor the Simulations Group's SMTN series.lsst-sitcomfor the SITCOMTN series.lsst-sqrefor the SQuaRE SQR series.lsst-tstnfor the TSTN series.lsst-sqre-testingfor the TESTN series.
Allow Cookiecutter to populate this variable.
This is the technote's URL in LSST's DocuShare archive. Leave empty if the technote hasn't been registered with DocuShare yet (which is currently true in most cases).
The technote's public URL on LSST the Docs. Allow cookiecutter to populate this variable.
A short description of the technote's content and purpose. This description is used in the repository's README and may be used in the abstract in the document itself.
The year of the initial copyright claim. Cookiecutter will automatically populate the current year.
The initial copyright holder. See Copyrights for LSST DM work and the COPYRIGHT file for more information.
The testn-000 directory is an example of a technote generated from the template defaults.
Example: .github/workflows/ci.yaml.
The GitHub Actions configuration file. CI is triggered whenever a technote is pushed to GitHub, and is responsible for deploying the technote to LSST the Docs.
This file configures Dependabot to automatically update the technote's dependencies with pull requests on GitHub.
Example: .pre-commit-config.yaml.
This file configures the Pre-commit hooks that can run to validate and format the content with every commit.
Example: conf.py.
The Sphinx configuration file.
The basic Sphinx configuration comes our Documenteer package, but you can append the typical configuration variables to the end of that conf.py to customize the Sphinx build.
Example: COPYRIGHT.
Record copyright claims in this file, one line per institution. See the copyright template and Copyrights for LSST DM work and the COPYRIGHT file.
Example: index.md.
This is the file that your technote's content should go into.
Example: LICENSE.
Generally speaking, LSST documentation is licensed under CC-BY 4.0. See Licensing LSST DM source code and content in the Developer Guide for more information.
Example: local.bib.
Add BibTeX citations to this file that aren't already available in lsst-texmf. See the Updating bibliographies documentation in lsst-texmf for how to migrate local bibliography data upstream into lsst-texmf.
Example: Makefile.
The Makefile runs the local Sphinx build for authors on their local machines, and is also used by the continuous integration build (see .github/workflows/ci.yaml).
Example: README.md.
The README advertises the technote to GitHub visitors and provides instructions for authors.
Example: requirements.txt.
The requirements.txt file defines build dependencies for both authors, on your local system, and for the CI system.
If your technote requires additional Python Packages and Sphinx extensions to build, add those requirements to this file.
Generally speaking, the documenteer dependencies only needs to be updated if the build breaks or you need new features from Documenteer.
Example: technote.toml.
This is the configuration file for the technote. It contains both metadata about the document (authors, draft/deprecation status, etc.) and configuration for the Sphinx build. See the Documenteer documentation for details.
Example: tox.ini
This is the Tox configuration file. Technotes use tox to build the document in an isolated Python environment. The Makefile runs the build through tox.