LSST document (including LDM, DMTN) template

The document template lets you create new documents using the lsstdoc class. These can be project controlled documents (LPM, LSE, LDM, for example) or technical notes (DMTN, SQR, SMTN). This page describes how to use the document template.

See also

For background, see Creating new documents with templates.

For help with using the lsstdoc class, see Using the lsstdoc document class.

Note

We intend to provide a chatbot for creating new documents that handles creating a GitHub repository, filling in the template, and deploying the document as a website. In the meantime, you can still manually create new documents with this template.

Invoking the template

After you have set up cookiecutter and cloned the lsst-texmf repository, you can create a document by pointing cookiecutter at lsst-texmf’s templates/document directory. For example, from a directory containing a lsst-texmf clone:

cookiecutter lsst-texmf/templates/document

Cookiecutter will prompt you to configure your document. See the next section for details.

Template configurations

This section describes configurations requested by cookiecutter.

series

Handle of the documentation series. Technical notes can be DMTN, SQR, or SMTN (see the DM Developer Guide for more information).

serial_number

Serial number of the document. For project documents, this number is pre-assigned by DocuShare. For technical notes, you can claim the next available number yourself. These links show existing technical notes in each series:

• DMTN
• SQR
• SMTN

github_org

Documents belong in specific GitHub organizations:

• LDM: lsst
• DMTN: lsst-dm
• SQR: lsst-sqr
• SMTN: lsst-sims

docushare_url

Provide a URL to the document in DocuShare, if available. Technotes might not have DocuShare handles. Using the https://ls.st short link to the document’s version page in DocuShare is effective. For example: 'https://ls.st/ldm-151*'.

title

Title of the document, without a handle prefix.

first_author

The first and last name of the document’s primary author. You can add additional authors later to the \author command in the generated document.

abstract

Abstract or summary of the document. This abstract appears both in the document’s \setDocAbstract command an in the README.

copyright_year

Year when copyright is first claimed.

copyright_hold

Institution that holds the document’s copyright.

license_cc_by

If true, a Creative Commons Attribution license is added to the README.

Deploying the document

Note

These instructions will help you deploy your documentation project to GitHub and LSST the Docs. In the future, a chatbot service will automate these steps.

After creating a document directory with cookiecutter, the next step is to initialize it as a Git repository and push that repository to GitHub. Keep in mind the organization you host the repository in must match the organization name provided to cookiecutter. Also, the repository name should be the document’s handle in lowercase (for example, lsst-sqre/sqr-019 for the SQR-019 technical note).

Once the document is on GitHub, notify the #dm-docs channel on Slack that a new document is ready to be deployed to LSST the Docs.