Merge pull request #2 from lsst-sitcom/tickets/SITCOM-1131

Tickets/sitcom 1131
lsst-sitcom · May 14, 2024 · 9a67953 · 9a67953
2 parents 129f66f + a77ac86
commit 9a67953
Show file tree

Hide file tree

Showing 56 changed files with 1,672 additions and 14,804 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1 +1,5 @@
 _build/
+.technote/
+.tox/
+venv/
+.venv/
diff --git a/Makefile b/Makefile
@@ -1,58 +1,26 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    = -W --keep-going -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.)
-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) .
-
-.PHONY: help clean html epub changes linkcheck refresh-bib
-
-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/"
-
-clean:
-	rm -rf $(BUILDDIR)/*
+.PHONY:
+init:
+	pip install tox pre-commit
+	pre-commit install
 
+.PHONY:
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	tox run -e html
 
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+.PHONY:
+lint:
+	tox run -e lint,linkcheck
 
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
+.PHONY:
+add-author:
+	tox run -e add-author
 
-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."
+.PHONY:
+sync-authors:
+	tox run -e sync-authors
 
-refresh-bib:
-	refresh-lsst-bib -d lsstbib
-	@echo
-	@echo "Commit the new bibliographies: git add lsstbib && git commit -m \"Update bibliographies.\""
+.PHONY:
+clean:
+	rm -rf _build
+	rm -rf .technote
+	rm -rf .tox
diff --git a/README.rst b/README.rst
@@ -1,11 +1,7 @@
 .. image:: https://img.shields.io/badge/sitcomtn--101-lsst.io-brightgreen.svg
-   :target: https://sitcomtn-101.lsst.io
+   :target: https://sitcomtn-101.lsst.io/
 .. image:: https://github.com/lsst-sitcom/sitcomtn-101/workflows/CI/badge.svg
    :target: https://github.com/lsst-sitcom/sitcomtn-101/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.#####
 
 #####################################################
 Investigation into vibrations in the M1M3 due to FCUs
@@ -18,61 +14,37 @@ This technote uses data from the VMS, dc accelerometers and IMS to estimate the
 
 **Links:**
 
-- Publication URL: https://sitcomtn-101.lsst.io
+- Publication URL: https://sitcomtn-101.lsst.io/
 - Alternative editions: https://sitcomtn-101.lsst.io/v
 - GitHub repository: https://github.com/lsst-sitcom/sitcomtn-101
 - Build system: https://github.com/lsst-sitcom/sitcomtn-101/actions/
 
-
 Build this technical note
 =========================
 
-You can clone this repository and build the technote locally with `Sphinx`_:
+You can clone this repository and build the technote locally if your system has Python 3.11 or later:
 
 .. code-block:: bash
 
    git clone https://github.com/lsst-sitcom/sitcomtn-101
    cd sitcomtn-101
-   pip install -r requirements.txt
+   make init
    make html
 
-.. note::
-
-   In a Conda_ environment, ``pip install -r requirements.txt`` doesn't work as expected.
-   Instead, ``pip`` install the packages listed in ``requirements.txt`` individually.
+Repeat the ``make html`` command to rebuild the technote after making changes.
+If you need to delete any intermediate files for a clean build, run ``make clean``.
 
 The built technote is located at ``_build/html/index.html``.
 
-Editing this technical note
-===========================
-
-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.
-
-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.
-
-The published technote at https://sitcomtn-101.lsst.io will be automatically rebuilt whenever you push your changes to the ``main`` branch on `GitHub <https://github.com/lsst-sitcom/sitcomtn-101>`_.
+Publishing changes to the web
+=============================
 
-Updating metadata
-=================
+This technote is published to https://sitcomtn-101.lsst.io/ whenever you push changes to the ``main`` branch on GitHub.
+When you push changes to a another branch, a preview of the technote is published to https://sitcomtn-101.lsst.io/v.
 
-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.
-
-Using the bibliographies
-========================
-
-The bibliography files in ``lsstbib/`` are copies from `lsst-texmf`_.
-You can update them to the current `lsst-texmf`_ versions with::
-
-   make refresh-bib
-
-Add new bibliography items to the ``local.bib`` file in the root directory (and later add them to `lsst-texmf`_).
+Editing this technical note
+===========================
 
-.. _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
+The main content of this technote is in ``index.rst`` (a reStructuredText file).
+Metadata and configuration is in the ``technote.toml`` file.
+For guidance on creating content and information about specifying metadata and configuration, see the Documenteer documentation: https://documenteer.lsst.io/technotes.
diff --git a/_static/images/TMA_position.png b/_static/images/TMA_position.png
diff --git a/_static/images/TMA_spike.png b/_static/images/TMA_spike.png
diff --git a/_static/images/displacement_comp.png b/_static/images/displacement_comp.png
diff --git a/_static/images/duration_comp.png b/_static/images/duration_comp.png
diff --git a/_static/images/psd_cumul_disp_sensor_1_axis_x.png b/_static/images/psd_cumul_disp_sensor_1_axis_x.png
diff --git a/_static/images/psd_cumul_disp_sensor_1_axis_y.png b/_static/images/psd_cumul_disp_sensor_1_axis_y.png
diff --git a/_static/images/psd_cumul_disp_sensor_1_axis_z.png b/_static/images/psd_cumul_disp_sensor_1_axis_z.png
diff --git a/_static/images/psd_cumul_disp_sensor_2_axis_x.png b/_static/images/psd_cumul_disp_sensor_2_axis_x.png
diff --git a/_static/images/psd_cumul_disp_sensor_2_axis_y.png b/_static/images/psd_cumul_disp_sensor_2_axis_y.png
diff --git a/_static/images/psd_cumul_disp_sensor_2_axis_z.png b/_static/images/psd_cumul_disp_sensor_2_axis_z.png
diff --git a/_static/images/psd_cumul_disp_sensor_3_axis_x.png b/_static/images/psd_cumul_disp_sensor_3_axis_x.png
diff --git a/_static/images/psd_cumul_disp_sensor_3_axis_y.png b/_static/images/psd_cumul_disp_sensor_3_axis_y.png
diff --git a/_static/images/psd_cumul_disp_sensor_3_axis_z.png b/_static/images/psd_cumul_disp_sensor_3_axis_z.png
diff --git a/_static/images/psd_sensor_1_axis_x.png b/_static/images/psd_sensor_1_axis_x.png
diff --git a/_static/images/psd_sensor_1_axis_y.png b/_static/images/psd_sensor_1_axis_y.png
diff --git a/_static/images/psd_sensor_1_axis_z.png b/_static/images/psd_sensor_1_axis_z.png
diff --git a/_static/images/psd_sensor_2_axis_x.png b/_static/images/psd_sensor_2_axis_x.png
diff --git a/_static/images/psd_sensor_2_axis_y.png b/_static/images/psd_sensor_2_axis_y.png
diff --git a/_static/images/psd_sensor_2_axis_z.png b/_static/images/psd_sensor_2_axis_z.png
diff --git a/_static/images/psd_sensor_3_axis_x.png b/_static/images/psd_sensor_3_axis_x.png
diff --git a/_static/images/psd_sensor_3_axis_y.png b/_static/images/psd_sensor_3_axis_y.png
diff --git a/_static/images/psd_sensor_3_axis_z.png b/_static/images/psd_sensor_3_axis_z.png
diff --git a/_static/images/psd_speed_0.png b/_static/images/psd_speed_0.png
diff --git a/_static/images/psd_speed_10.png b/_static/images/psd_speed_10.png
diff --git a/_static/images/psd_speed_100.png b/_static/images/psd_speed_100.png
diff --git a/_static/images/psd_speed_20.png b/_static/images/psd_speed_20.png
diff --git a/_static/images/psd_speed_30.png b/_static/images/psd_speed_30.png
diff --git a/_static/images/psd_speed_40.png b/_static/images/psd_speed_40.png
diff --git a/_static/images/psd_speed_50.png b/_static/images/psd_speed_50.png
diff --git a/_static/images/psd_speed_60.png b/_static/images/psd_speed_60.png
diff --git a/_static/images/psd_speed_70.png b/_static/images/psd_speed_70.png
diff --git a/_static/images/psd_speed_80.png b/_static/images/psd_speed_80.png
diff --git a/_static/images/psd_speed_90.png b/_static/images/psd_speed_90.png
diff --git a/_static/images/sampling.png b/_static/images/sampling.png
diff --git a/_static/images/total_1_psd_comp.png b/_static/images/total_1_psd_comp.png
diff --git a/_static/images/total_2_psd_comp.png b/_static/images/total_2_psd_comp.png
diff --git a/_static/images/total_3_psd_comp.png b/_static/images/total_3_psd_comp.png
diff --git a/_static/images/vms_telemetry_1.png b/_static/images/vms_telemetry_1.png
diff --git a/_static/images/vms_telemetry_2.png b/_static/images/vms_telemetry_2.png
diff --git a/_static/images/vms_telemetry_zoom_1.png b/_static/images/vms_telemetry_zoom_1.png
diff --git a/conf.py b/conf.py
@@ -1,9 +1,6 @@
-"""Sphinx configuration.
+# See the Documenteer docs for how to customize conf.py:
+# https://documenteer.lsst.io/technotes/
 
-To learn more about the Sphinx configuration for technotes, and how to
-customize it, see:
+from documenteer.conf.technote import *  # noqa F401 F403
 
-https://documenteer.lsst.io/technotes/configuration.html
-"""
-
-from documenteer.conf.technote import *  # noqa: F401, F403
+exclude_patterns.append("notebooks")