Skip to content

Latest commit

 

History

History

technote_latex

README.md

technote_latex

LSST technical note repository, formatted as LaTeX (lsstdoc class).

This template generates a new technical note (technote) repository based on LaTeX (specifically the lsstdoc class). LSST 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.

Template variables

cookiecutter.org

The organization responsible for the document. This is used as an argument for the lsstdoc class.

cookiecutter.series

The identifier of the technote series. Choose the series that fits the document's purpose or aligns with the organization creating the document:

  • DMTN for Data Management technical notes. See DMTN-000.
  • ITTN for LSST IT technical notes.
  • RTN for Rubin Observatory operations technical notes (all departments).
  • PSTN for Project Science Team technical notes.
  • SMTN for Simulations Group technical notes. See SMTN-000.
  • SITCOMTN for Systems Integration, Testing, and Commissioning notes.
  • SQR for SQuaRE technical notes. See SQR-000.
  • TSTN for Telescope & Site technical notes.
  • TESTN for testing the technical system. These notes may be purged at any time.

cookiecutter.serial_number

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.

cookiecutter.github_org

The GitHub organization where this technote resides. Choose a GitHub organization that matches the series:

  • lsst-dm for the DMTN series.
  • lsst-it for the ITTN series.
  • lsst for the RTN series.
  • lsst-pst for the PSTN series.
  • lsst-sims for the Simulations Group's SMTN series.
  • lsst-sitcom for the SITCOMTN series.
  • lsst-sqre for the SQuaRE SQR series.
  • lsst-sqre-testing for the TESTN series.
  • lsst-tstn for the TSTN series.

cookiecutter.title

The title of the technote.

cookiecutter.first_author

The name of the first author, formatted as First Last. Additional authors can be added later in the LaTeX source itself.

cookiecutter.abstract

A short description of the technote's content and purpose. This description is used in the repository's README and the abstract in the document itself.

cookiecutter.copyright_year

The year of the initial copyright claim. Cookiecutter will automatically populate the current year.

cookiecutter.copyright_holder

The initial copyright holder. See Copyrights for LSST DM work and the COPYRIGHT file for more information.

Examples

testn-000/

The testn-000 directory is an example of a LaTeX-formatted technote.

Files

.gitignore

Example: .gitignore.

The gitignore file ignores the built PDF product (which is persisted on LSST the Docs), as well as intermediate LaTeX build files (including meta.tex). The acronyms.tex file is not ignored so that make acronyms.tex does not need to be run for every document build.

.github/workflows/ci.yaml

Example: .github/workflows/ci.yaml.

The GitHub Actions workflow file. You shouldn't have to modify this file unless you have a novel preprocessing build step (see below).

Tip: GitHub Actions provides a flexible Python environment. It's likely easier to run preprocessing scripts directly from the GitHub actions environment, rather than within the lsst-texmf Docker container:

  • Install additional Python dependencies in the Python install step.
  • Add additional bash commands for preprocessing steps to run before the docker run step.
  • Structure your Makefile so that files built in advance in the GitHub actions environment are automatically used as-is by the docker run command.

For more information about using the CI environment, see the GitHub actions workflow documentation.

acronyms.tex

Example: acronyms.tex.

This file is generated and updated by the make acronyms.tex command.

COPYRIGHT

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.

LICENSE

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.

local.bib

Example: local.bib.

Add BibTeX citations to this file that aren't already available in lsst-texmf (the lsstbib/. See the Updating bibliographies documentation in lsst-texmf for how to migrate local bibliography data upstream into lsst-texmf.

Makefile

Example: Makefile.

The built-in targets are:

  • make: compiles the PDF document by running xelatex and bibtex iteratively. This command is used by the CI environment that pushes the PDF to LSST the Docs (lsst.io). See the .travis.yml file.
  • make acronyms.tex: regenerates the acronyms.tex file.

Add additional make targets to do preprocessing steps (such as running a Python script to generate tables or figures).

myacronyms.txt

Example: Makefile.

List acronyms in this file that are not found in lsst-texmf's lsstacronyms.txt or glossary.txt, or that have multiple definitions (put the one you want in the local myacronyms.txt file).

The format for each line of this file is:

ACRONYM:Definition

For example:

MIA:Missing In Action

README.rst

Example: README.rst.

The README advertises the technote to GitHub visitors and provides instructions for authors.

You can update the abstract in the README and add author instructions as necessary.

skipacronyms.txt

Example: skipacronyms.txt.

This file contains a list acronyms that should be ignored by generateAcronyms.py (the script behind make acronyms.txt). If your document contains acronym-like strings that aren't acronyms, you can add them to skipacronyms.txt.

{{cookiecutter.series.upper()}}-{{cookiecutter.serial_number}}.tex

Example: TESTN-000.tex

This file contains the content of the technote itself. Either write directly in this file, or use the \input command to include content from other files.

For more information about writing a LaTeX document with the lsstdoc class file, see Using the lsstdoc document class.