convert to new documenteer

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yaml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0 # full history for metadata
           submodules: true
@@ -20,15 +20,14 @@ jobs:
         working-directory: ./milestones
 
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
-          python-version: 3.7
+          python-version: '3.11'
 
       - name: Python install
         run: |
           python -m pip install --upgrade pip
           python -m pip install -r requirements.txt
-          python -m pip install "ltd-conveyor<2.0.0"
           python -m pip install -r milestones/requirements.txt
 
       - name: Install Graphviz

.gitignore

@@ -1,5 +1,8 @@
 _build/
-lsstbib/
-_static/burndown.png
-_static/graph_02C.??.png
-_static/graph_02C.??.png.dot
+.technote/
+.tox/
+venv/
+.venv/
+_static/gra*
+_static/burn*
+.idea

.pre-commit-config.yaml

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

Makefile

@@ -1,27 +1,33 @@
-# Makefile for Sphinx documentation
-#
+.PHONY:
+init:
+	pip install tox pre-commit
+	pre-commit install
 
-# You can set these variables from the command line.
-SPHINXOPTS    = -n
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
+.PHONY:
+html: index.rst _static/burndown.png _static/graph_02C.00.png _static/graph_02C.03.png _static/graph_02C.04.png _static/graph_02C.05.png _static/graph_02C.06.png _static/graph_02C.07.png _static/graph_02C.08.png _static/graph_02C.09.png _static/graph_02C.10.png _static/graph_02C.11.png
+	tox run -e html
 
-# 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
+.PHONY:
+lint:
+	tox run -e lint,linkcheck
 
-# 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:
+add-author:
+	tox run -e add-author
 
-.PHONY: index.rst _static/burndown.png help clean html epub changes linkcheck refresh-bib
+.PHONY:
+sync-authors:
+	tox run -e sync-authors
 
-index.rst: bin/generate_dmtn.py refresh-bib
+.PHONY:
+clean:
+	rm -rf _build
+	rm -rf .technote
+	rm -rf .tox
+	git checkout index.rst
+	rm -f _static/burndown.png
+
+index.rst: bin/generate_dmtn.py
 	PYTHONPATH=milestones python3 bin/generate_dmtn.py
 
 _static/burndown.png:
@@ -31,41 +37,5 @@ _static/graph_%.png:
 	PYTHONPATH=milestones python3 milestones/milestones.py graph --wbs=$* [email protected]
 	dot -Tpng [email protected] > $@
 
-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)/*
-	git checkout index.rst
-	rm -f _static/burndown.png
-
-html: index.rst _static/burndown.png _static/graph_02C.00.png _static/graph_02C.03.png _static/graph_02C.04.png _static/graph_02C.05.png _static/graph_02C.06.png _static/graph_02C.07.png _static/graph_02C.08.png _static/graph_02C.09.png _static/graph_02C.10.png
-	$(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:
-	mkdir -p lsstbib
-	refresh-lsst-bib -d lsstbib
-	@echo
-	@echo "Commit the new bibliographies: git add lsstbib && git commit -m \"Update bibliographies.\""

README.rst

@@ -1,11 +1,7 @@
 .. image:: https://img.shields.io/badge/dmtn--158-lsst.io-brightgreen.svg
-   :target: https://dmtn-158.lsst.io
+   :target: https://dmtn-158.lsst.io/
 .. image:: https://github.com/lsst-dm/dmtn-158/workflows/CI/badge.svg
    :target: https://github.com/lsst-dm/dmtn-158/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.#####
 
 ####################
 DM Milestone Summary
@@ -18,61 +14,37 @@ This note summarizes all milestones currently being tracked by the Data Manageme
 
 **Links:**
 
-- Publication URL: https://dmtn-158.lsst.io
+- Publication URL: https://dmtn-158.lsst.io/
 - Alternative editions: https://dmtn-158.lsst.io/v
 - GitHub repository: https://github.com/lsst-dm/dmtn-158
 - Build system: https://github.com/lsst-dm/dmtn-158/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-dm/dmtn-158
    cd dmtn-158
-   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://dmtn-158.lsst.io will be automatically rebuilt whenever you push your changes to the ``master`` branch on `GitHub <https://github.com/lsst-dm/dmtn-158>`_.
+Publishing changes to the web
+=============================
 
-Updating metadata
-=================
+This technote is published to https://dmtn-158.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://dmtn-158.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,29 +1,7 @@
-#!/usr/bin/env python
-#
-# Sphinx configuration file
-# see metadata.yaml in this repo to update document-specific metadata
+# See the Documenteer docs for how to customize conf.py:
+# https://documenteer.lsst.io/technotes/
 
-import datetime
-import os
-from documenteer.sphinxconfig.technoteconf import configure_technote
+from documenteer.conf.technote import *  # noqa F401 F403
 
-# Ingest settings from metadata.yaml and use documenteer's configure_technote()
-# to build a Sphinx configuration that is injected into this script's global
-# namespace.
-metadata_path = os.path.join(os.path.dirname(__file__), 'metadata.yaml')
-with open(metadata_path, 'r') as f:
-    confs = configure_technote(f)
+exclude_patterns.extend(["*.md", "**/*md", ".tox/*", "milestones/*"])
 
-# Set revision date to the current date.
-# The “true” revision is really set by the version of the data used in the
-# milestones repository, but that's awkward to work with.
-confs['html_context']['last_revised'] = datetime.datetime.now().strftime("%Y-%m-%d")
-
-g = globals()
-g.update(confs)
-
-# Add intersphinx inventories as needed
-# http://www.sphinx-doc.org/en/stable/ext/intersphinx.html
-# Example:
-#
-#     intersphinx_mapping['python'] = ('https://docs.python.org/3', None)

index.rst

@@ -1,6 +1,13 @@
+####################
+DM Milestone Summary
+####################
+
+.. abstract::
+
+   This note summarizes all milestones currently being tracked by the Data Management subsystem.
+
 .. Auto-generated by bin/generate_dmtn.py on Fri Jan 27 16:53:50 2023 - DO NOT EDIT
 
-:tocdepth: 1
 
 .. |LSST-1590| replace:: LSST-1590
 .. |LSST-1630| replace:: *LSST-1630*
@@ -10013,7 +10020,6 @@ There is robust functionality for performing large distributed catalog operation
 Bibliography
 ============
 
-.. bibliography:: lsstbib/refs.bib lsstbib/refs_ads.bib lsstbib/books.bib lsstbib/lsst-dm.bib lsstbib/lsst.bib
-   :style: lsst_aa
+.. bibliography::
 
 

requirements.txt

@@ -1,5 +1,3 @@
-documenteer[technote]>=0.5.4,<0.6.0
-matplotlib
-jira
-xlrd
-keyring
+ltd-conveyor
+tox
+documenteer[technote]>=1.0,<2.0

technote.toml

@@ -0,0 +1,17 @@
+[technote]
+id = "DMTN-158"
+series_id = "DMTN"
+canonical_url = "https://dmtn-158.lsst.io/"
+github_url = "https://github.com/lsst-dm/dmtn-158"
+github_default_branch = "main"
+organization.name = "Vera C. Rubin Observatory"
+organization.ror = "https://ror.org/048g3cy84"
+license.id = "CC-BY-4.0"
+[[technote.authors]]
+name = {given = "William", family = "O'Mullane"}
+internal_id = "omullanew"
+orcid = "https://orcid.org/0000-0003-4141-6195"
+[[technote.authors.affiliations]]
+name = "Vera C. Rubin Observatory"
+internal_id = "RubinObsC"
+address = "Avenida Juan Cisternas #1500, La Serena, Chile"

tox.ini

@@ -0,0 +1,31 @@
+[tox]
+environments = html
+isolated_build = True
+
+[testenv]
+skip_install = true
+deps =
+    -rrequirements.txt
+    -rmilestones/requirements.txt
+
+
+[testenv:html]
+commands =
+   sphinx-build --keep-going -n -W -T -b html -d _build/doctrees . _build/html
+
+[testenv:linkcheck]
+commands =
+   sphinx-build --keep-going -n -W -T -b linkcheck -d _build/doctrees . _build/linkcheck
+
+[testenv:lint]
+deps = pre-commit
+commands =
+   pre-commit run --all-files
+
+[testenv:add-author]
+commands =
+    documenteer technote add-author
+
+[testenv:sync-authors]
+commands =
+    documenteer technote sync-authors