migration to markdown

.github/dependabot.yml

@@ -4,3 +4,8 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.gitignore

@@ -1 +1,5 @@
 _build/
+.technote/
+.tox/
+venv/
+.venv/

.pre-commit-config.yaml

@@ -1,5 +1,7 @@
 repos:
-  - repo: https://github.com/kynan/nbstripout
-    rev: 0.6.1
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
     hooks:
-      - id: nbstripout
+      # - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml

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

README.rst

@@ -1,11 +1,7 @@
 .. image:: https://img.shields.io/badge/sitcomtn--066-lsst.io-brightgreen.svg
-   :target: https://sitcomtn-066.lsst.io
+   :target: https://sitcomtn-066.lsst.io/
 .. image:: https://github.com/lsst-sitcom/sitcomtn-066/workflows/CI/badge.svg
    :target: https://github.com/lsst-sitcom/sitcomtn-066/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.#####
 
 ######################################
 SITCOM-716: Encoder Disagreement Study
@@ -18,61 +14,37 @@ During observing, it has been noticed that the encoders sometimes disagree with
 
 **Links:**
 
-- Publication URL: https://sitcomtn-066.lsst.io
+- Publication URL: https://sitcomtn-066.lsst.io/
 - Alternative editions: https://sitcomtn-066.lsst.io/v
 - GitHub repository: https://github.com/lsst-sitcom/sitcomtn-066
 - Build system: https://github.com/lsst-sitcom/sitcomtn-066/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-066
    cd sitcomtn-066
-   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-066.lsst.io will be automatically rebuilt whenever you push your changes to the ``main`` branch on `GitHub <https://github.com/lsst-sitcom/sitcomtn-066>`_.
+Publishing changes to the web
+=============================
 
-Updating metadata
-=================
+This technote is published to https://sitcomtn-066.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-066.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.

conf.py

@@ -1,9 +1,4 @@
-"""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:
-
-https://documenteer.lsst.io/technotes/configuration.html
-"""
-
-from documenteer.conf.technote import *  # noqa: F401, F403
+from documenteer.conf.technote import *  # noqa F401 F403

index.rst → index.md

@@ -1,55 +1,53 @@
-:tocdepth: 1
+# SITCOM-716: Encoder Disagreement Study
 
-.. sectnum::
 
-.. Metadata such as the title, authors, and description are set in metadata.yaml
+% Metadata such as the title, authors, and description are set in metadata.yaml
 
-.. TODO: Delete the note below before merging new content to the main branch.
 
-.. note::
-
-   **This technote is a work-in-progress.**
-
-Abstract
-========
+## Abstract
 
 During observing, it has been noticed that the encoders sometimes disagree with one another by significant amounts (up to 100+ degrees). Here we look at data from several days to try to find systematic patterns.
 
-Encoder Disagreement
-====================
+## Encoder Disagreement
 
 The following plots show the individual encoder positions as a function of time versus the "ActualPosition". The position given by the individual encoders seems to sometimes jump out of agreement with the others and to stay that way for up to a few hours. This behavior is seen in multiple encoders.
 
 Occassionally, encoder 3 will register a 360 offset in azimuth from the other encoders. This is presumably not inherently a problem, but could affect which encoders are used to calculate the "ActualPosition". (Note that In the included plots, the startracker is also sometimes off by 360 degrees.)
 
-The ActualPosition sometimes goes to zero, but this seems to happen independently for the azimuth and elevation. The small (<5 degree), high-frequency differences between the individual encoders and the ActualPosition seem to always happen during slews, where the encoders are sometimes all systematically offset from the ActualPosition.
+The ActualPosition sometimes goes to zero, but this seems to happen independently for the azimuth and elevation. The small (\<5 degree), high-frequency differences between the individual encoders and the ActualPosition seem to always happen during slews, where the encoders are sometimes all systematically offset from the ActualPosition.
 
 03-15-2023:
 
-.. figure:: /_static/EncoderDisagreement_03_15.png 
-   :name: encoders-03-15
+:::{figure} /_static/EncoderDisagreement_03_15.png
+:name: encoders-03-15
+:::
 
 03-16-2023:
 
-.. figure:: /_static/EncoderDisagreement_03_16.png 
+:::{figure} /_static/EncoderDisagreement_03_16.png
+:::
 
 03-17-2023:
 
-.. figure:: /_static/EncoderDisagreement_03_16.png 
+:::{figure} /_static/EncoderDisagreement_03_16.png
+:::
 
 03-18-2023:
 
-.. figure:: /_static/EncoderDisagreement_03_16.png 
+:::{figure} /_static/EncoderDisagreement_03_16.png
+:::
 
 03-21-2023:
 
-.. figure:: /_static/EncoderDisagreement_03_21.png 
+:::{figure} /_static/EncoderDisagreement_03_21.png
+:::
 
 03-22-2023:
 
-.. figure:: /_static/EncoderDisagreement_03_22.png 
+:::{figure} /_static/EncoderDisagreement_03_22.png
+:::
 
 03-23-2023:
 
-.. figure:: /_static/EncoderDisagreement_03_23.png 
-
+:::{figure} /_static/EncoderDisagreement_03_23.png
+:::