Merge pull request #1 from lsst/u/leanne/convert-to-latex

Convert document to latex

.github/workflows/ci.yaml

@@ -1,12 +1,41 @@
 name: CI
 
-'on': [push, pull_request, workflow_dispatch]
+"on": [push, pull_request]
 
 jobs:
-  call-workflow:
-    uses: lsst-sqre/rubin-sphinx-technote-workflows/.github/workflows/ci.yaml@v1
-    with:
-      handle: rtn-038
-    secrets:
-      ltd_username: ${{ secrets.LTD_USERNAME }}
-      ltd_password: ${{ secrets.LTD_PASSWORD }}
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0 # full history for metadata
+          submodules: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Python install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v1
+        with:
+          username: sqrereadonly
+          password: ${{ secrets.DOCKERHUB_SQREREADONLY_TOKEN }}
+
+      - name: TeX build
+        run: |
+          docker run --rm -v `pwd`:/workspace -w /workspace lsstsqre/lsst-texmf:latest sh -c 'make'
+
+      - name: Landing page upload
+        if: ${{ github.event_name == 'push' }}
+        env:
+          LTD_PASSWORD: ${{ secrets.LTD_PASSWORD }}
+          LTD_USERNAME: ${{ secrets.LTD_USERNAME }}
+        run: |
+          lander --upload --pdf RTN-038.pdf --lsstdoc RTN-038.tex --ltd-product rtn-038

COPYRIGHT

@@ -1 +1 @@
-Copyright 2022 Association of Universities for Research in Astronomy, Inc. (AURA)
+Copyright 2024 Association of Universities for Research in Astronomy, Inc. (AURA)

Makefile

@@ -1,58 +1,48 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    = -n
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
-
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Try 'running pip install -r requirements.txt' to get the necessary Python dependencies.)
+DOCTYPE = RTN
+DOCNUMBER = 038
+DOCNAME = $(DOCTYPE)-$(DOCNUMBER)
+
+tex = $(filter-out $(wildcard *acronyms.tex) , $(wildcard *.tex))
+
+GITVERSION := $(shell git log -1 --date=short --pretty=%h)
+GITDATE := $(shell git log -1 --date=short --pretty=%ad)
+GITSTATUS := $(shell git status --porcelain)
+ifneq "$(GITSTATUS)" ""
+	GITDIRTY = -dirty
 endif
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+export TEXMFHOME ?= lsst-texmf/texmf
+
+# Add aglossary.tex as a dependancy here if you want a glossary (and remove acronyms.tex)
+$(DOCNAME).pdf: $(tex) meta.tex local.bib acronyms.tex
+	latexmk -bibtex -xelatex -f $(DOCNAME)
+#	makeglossaries $(DOCNAME)
+#	xelatex $(DOCNAME)
+# For glossary uncomment the 2 lines above
+
+
+# Acronym tool allows for selection of acronyms based on tags - you may want more than DM
+acronyms.tex: $(tex) myacronyms.txt
+	$(TEXMFHOME)/../bin/generateAcronyms.py -t "DM" $(tex)
 
-.PHONY: help clean html epub changes linkcheck refresh-bib
+# If you want a glossary you must manually run generateAcronyms.py  -gu to put the \gls in your files.
+aglossary.tex :$(tex) myacronyms.txt
+	generateAcronyms.py  -g $(tex)
 
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html         to make standalone HTML files"
-	@echo "  epub         to make an epub"
-	@echo "  linkcheck    to check all external links for integrity"
-	@echo "  refresh-bib  to update LSST bibliographies in lsstbib/"
 
+.PHONY: clean
 clean:
-	rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-refresh-bib:
-	refresh-lsst-bib -d lsstbib
-	@echo
-	@echo "Commit the new bibliographies: git add lsstbib && git commit -m \"Update bibliographies.\""
+	latexmk -c
+	rm -f $(DOCNAME).{bbl,glsdefs,pdf}
+	rm -f meta.tex
+
+.FORCE:
+
+meta.tex: Makefile .FORCE
+	rm -f $@
+	touch $@
+	printf '%% GENERATED FILE -- edit this in the Makefile\n' >>$@
+	printf '\\newcommand{\\lsstDocType}{$(DOCTYPE)}\n' >>$@
+	printf '\\newcommand{\\lsstDocNum}{$(DOCNUMBER)}\n' >>$@
+	printf '\\newcommand{\\vcsRevision}{$(GITVERSION)$(GITDIRTY)}\n' >>$@
+	printf '\\newcommand{\\vcsDate}{$(GITDATE)}\n' >>$@

README.rst

@@ -1,78 +1,65 @@
-.. image:: https://img.shields.io/badge/rtn--038-lsst.io-brightgreen.svg
+The document provides the detailed mathematical definitions for all Rubin/LSST science performance metrics. 
+It provides quantitative definitions for all the science performance metrics specified in the LSST Science Requirements document and derived documents as well as additional metrics defined as part of system development... image:: https://img.shields.io/badge/rtn--038-lsst.io-brightgreen.svg
    :target: https://rtn-038.lsst.io
 .. image:: https://github.com/lsst/rtn-038/workflows/CI/badge.svg
    :target: https://github.com/lsst/rtn-038/actions/
-..
-  Uncomment this section and modify the DOI strings to include a Zenodo DOI badge in the README
-  .. image:: https://zenodo.org/badge/doi/10.5281/zenodo.#####.svg
-     :target: http://dx.doi.org/10.5281/zenodo.#####
 
-#################################
-Rubin Science Performance Metrics
-#################################
+###################################################################
+Migration Plan for Construction Project Documentation to Operations
+###################################################################
 
 RTN-038
 =======
 
-The document provides the detailed mathematical definitions for all normative LSST science performance metrics 
+The document provides the detailed mathematical definitions for all Rubin/LSST science performance metrics. 
+It provides quantitative definitions for all the science performance metrics specified in the LSST Science Requirements document and derived documents as well as additional metrics defined as part of system development.
 
-**Links:**
+Links
+=====
 
-- Publication URL: https://rtn-038.lsst.io
-- Alternative editions: https://rtn-038.lsst.io/v
-- GitHub repository: https://github.com/lsst/rtn-038
-- Build system: https://github.com/lsst/rtn-038/actions/
+- Live drafts: https://rtn-038.lsst.io
+- GitHub: https://github.com/lsst/rtn-038
 
+Build
+=====
 
-Build this technical note
-=========================
+This repository includes lsst-texmf_ as a Git submodule.
+Clone this repository::
 
-You can clone this repository and build the technote locally with `Sphinx`_:
+    git clone --recurse-submodules https://github.com/lsst/rtn-038
 
-.. code-block:: bash
+Compile the PDF::
 
-   git clone https://github.com/lsst/rtn-038
-   cd rtn-038
-   pip install -r requirements.txt
-   make html
+    make
 
-.. note::
+Clean built files::
 
-   In a Conda_ environment, ``pip install -r requirements.txt`` doesn't work as expected.
-   Instead, ``pip`` install the packages listed in ``requirements.txt`` individually.
+    make clean
 
-The built technote is located at ``_build/html/index.html``.
+Updating acronyms
+-----------------
 
-Editing this technical note
-===========================
+A table of the technote's acronyms and their definitions are maintained in the ``acronyms.tex`` file, which is committed as part of this repository.
+To update the acronyms table in ``acronyms.tex``::
 
-You can edit the ``index.rst`` file, which is a reStructuredText document.
-The `DM reStructuredText Style Guide`_ is a good resource for how we write reStructuredText.
+    make acronyms.tex
 
-Remember that images and other types of assets should be stored in the ``_static/`` directory of this repository.
-See ``_static/README.rst`` for more information.
+*Note: this command requires that this repository was cloned as a submodule.*
 
-The published technote at https://rtn-038.lsst.io will be automatically rebuilt whenever you push your changes to the ``main`` branch on `GitHub <https://github.com/lsst/rtn-038>`_.
+The acronyms discovery code scans the LaTeX source for probable acronyms.
+You can ensure that certain strings aren't treated as acronyms by adding them to the `skipacronyms.txt <./skipacronyms.txt>`_ file.
 
-Updating metadata
-=================
+The lsst-texmf_ repository centrally maintains definitions for LSST acronyms.
+You can also add new acronym definitions, or override the definitions of acronyms, by editing the `myacronyms.txt <./myacronyms.txt>`_ file.
 
-This technote's metadata is maintained in ``metadata.yaml``.
-In this metadata you can edit the technote's title, authors, publication date, etc..
-``metadata.yaml`` is self-documenting with inline comments.
+Updating lsst-texmf
+-------------------
 
-Using the bibliographies
-========================
+`lsst-texmf`_ includes BibTeX files, the ``lsstdoc`` class file, and acronym definitions, among other essential tooling for LSST's LaTeX documentation projects.
+To update to a newer version of `lsst-texmf`_, you can update the submodule in this repository::
 
-The bibliography files in ``lsstbib/`` are copies from `lsst-texmf`_.
-You can update them to the current `lsst-texmf`_ versions with::
+   git submodule update --init --recursive
 
-   make refresh-bib
+Commit, then push, the updated submodule.
 
-Add new bibliography items to the ``local.bib`` file in the root directory (and later add them to `lsst-texmf`_).
-
-.. _Sphinx: http://sphinx-doc.org
-.. _DM reStructuredText Style Guide: https://developer.lsst.io/restructuredtext/style.html
-.. _this repo: ./index.rst
-.. _Conda: http://conda.pydata.org/docs/
-.. _lsst-texmf: https://lsst-texmf.lsst.io
+.. _lsst-texmf: https://github.com/lsst/lsst-texmf

RTN-038.tex

@@ -0,0 +1,74 @@
+\documentclass[OPS,authoryear,lsstdraft,toc]{lsstdoc}
+\input{meta}
+
+% Package imports go here.
+\usepackage{graphicx} 
+
+% Local commands go here.
+
+%If you want glossaries
+%\input{aglossary.tex}
+%\makeglossaries
+
+\title{Rubin Science Performance Metrics}
+
+% Optional subtitle
+% \setDocSubtitle{A subtitle}
+
+\author{%
+Leanne Guy, ....,  and the DM System Science Team
+}
+
+\setDocRef{RTN-038}
+\setDocUpstreamLocation{\url{https://github.com/lsst/rtn-038}}
+
+\date{\vcsDate}
+
+% Optional: name of the document's curator
+% \setDocCurator{The Curator of this Document}
+
+\setDocAbstract{%
+The document provides the detailed mathematical definitions for all Rubin/LSST science performance metrics. 
+It provides quantitative definitions for all the science performance metrics specified in the LSST Science Requirements document and derived documents as well as additional metrics defined as part of system development. 
+}
+
+% Change history defined here.
+% Order: oldest first.
+% Fields: VERSION, DATE, DESCRIPTION, OWNER NAME.
+% See LPM-51 for version number policy.
+\setDocChangeRecord{%
+  \addtohist{1}{2023-07-10}{First draft}{Leanne Guy}
+}
+
+\graphicspath{{figures/}} %Setting the graphicspath
+
+\begin{document}
+
+% Create the title page.
+\maketitle
+% Frequently for a technote we do not want a title page  uncomment this to remove the title page and changelog.
+% use \mkshorttitle to remove the extra pages
+
+% ADD CONTENT HERE
+\input{intro}
+\input{srd_metrics}
+\input{non_srd_metrics}
+
+\appendix
+
+% \input{AppendixExamples}
+
+% Include all the relevant bib files.
+% https://lsst-texmf.lsst.io/lsstdoc.html#bibliographies
+\section{References} \label{sec:bib}
+\renewcommand{\refname}{} % Suppress default Bibliography section
+\bibliography{local,lsst,lsst-dm,refs_ads,refs,books}
+
+% Make sure lsst-texmf/bin/generateAcronyms.py is in your path
+\section{Acronyms} \label{sec:acronyms}
+\input{acronyms.tex}
+% If you want glossary uncomment below -- comment out the two lines above
+%\printglossaries
+
+
+\end{document}