Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
125 lines (85 sloc) 4.73 KB

LSST document (including LDM, DMTN) template

The document template lets you create new documents using the :ref:`lsstdoc <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.

.. seealso::

   For background, see :ref:`templates`.

   For help with using the ``lsstdoc`` class, see :ref:`lsstdoc`.

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 :ref:`set up <template-set-up>` cookiecutter and cloned the lsst-texmf repository, you can create a document by pointing :command:`cookiecutter` at lsst-texmf’s :file:`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 :command:`cookiecutter`.

org

Which part of DM the note is from (this comes out on the title page):

  • PST - Project Science Team
  • DM - Data Management
  • SE - Systems Engineering
  • PMO - Project Office
  • POS - Operations
  • TS - Telescope and Site
series
Handle of the documentation series. Technical notes can be DMTN, SQR, PSTN, OPSTN'' 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:

github_org

Documents belong in specific GitHub organizations:

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 :file:`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 :file:`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.