Editing the class files¶
Changes can be made to any of the files in the
lsst-texmf repository by submitting a pull request in the normal manner.
Travis jobs automatically run when a PR is created to ensure that nothing has been broken and a pull request can only be merged if these checks pass.
Please obtain reviews of any non-trivial changes to
If new files are added to or old ones removed from the
texmf directory, please remember to run texhash in that directory in order to update the
This file is committed to the repository such that end users do not have to remember to update it themselves.
One goal of a shared repository containing the LSST LaTeX files, is to provide a shared source of truth for references to other documents. If a document is being cited that is not part of the current list, a pull request should be made, preferably using a ticket branch related to the main document development. If the automated tests pass, the PR can be self-merged without review. In this way, we can ensure that all documents agree on references without duplication and with minimum overhead.
Some things to remember:
- LSST documents are added to
lsst.bib. Any document available on DocuShare should use the
@DocuSharebib entry using the document handle as the key in the bib file. In the longer term, this file will be auto-generated from DocuShare and should always be up to date and should not require manual editing. Tech notes will also be defined in this file.
- LSST Data Management publications are added to
lsst-dm.bib. This file is used for published papers (ADS and non-ADS) and presentations. Do not use it for items stored on DocuShare. Presentations should use a key of form
- Any reference that can be found on ADS should be stored in
refs_ads.bibusing the standard ADS bibtex export. ADS entries should always be cited using the ADS Bibcode. This file should be used for arXiv entries obtained from ADS.
refs.bibshould be used for non-LSST references that can not be located on ADS.
books.bibshould be used for books that are not indexed by ADS.
Updating examples and tests¶
We welcome additional example files to be added to the
examples directory and test files to be added to the
If new features are added to class or style files, it is helpful to add example code that uses these features to allow them to be tested.
Once new files are added, ensure that they are built correctly by the
Makefile since that file is used to build the tests and examples on Travis.
Be sure to document your example in the Examples page.
This documentation site is produced by Sphinx from the
docs/ repository directory, and published with LSST the Docs to https://lsst-texmf.lsst.io.
For more information on writing reStructuredText-formatted documentation, see DM’s reStructuredText Style Guide.
You can contribute to the documentation using DM’s normal workflow.
When you have pushed a ticket branch to GitHub, you can find a rendered draft at https://lsst-texmf.lsst.io/v.
The main site at https://lsst-texmf.lsst.io updates automatically once your PR is merged to
Maintaining the Docker distribution¶
Docker images are automatically published as lsstsqre/lsst-texmf on Docker Hub through Travis CI. Contributors shouldn’t need to worry about updating the Docker distribution.
The following tags are generated through Travis:
- Tags also correspond to git branches and tags on GitHub.
The build system converts forward slashes in branch names to dashes in tags.
For example, the
tickets/DM-10642Git branch is published on Docker Hub as
travis-Ntags correspond to individual Travis CI builds.
The following components are involved in the Docker toolchain:
Dockerfiledefines the container. Note that
Dockerfileis only concerned with installing
TEXMFHOME. The lsstsqre/lsst-texlive base image provides TeX Live and tools like make and git.
.travis.ymlfile runs the Docker image build and push in the Travis CI environment.
bin/travis-docker-deploy.shscript tags the images according to the above scheme and pushes those images to Docker Hub.