Merge pull request #5 from lsst-sqre/tickets/tickets/DM-42142

DM-42124: Migrate to new technote format

.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

@@ -0,0 +1,12 @@
+name: CI
+
+'on': [push, pull_request, workflow_dispatch]
+
+jobs:
+  call-workflow:
+    uses: lsst-sqre/rubin-sphinx-technote-workflows/.github/workflows/ci.yaml@v1
+    with:
+      handle: sqr-000
+    secrets:
+      ltd_username: ${{ secrets.LTD_USERNAME }}
+      ltd_password: ${{ secrets.LTD_PASSWORD }}

.gitignore

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

.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,52 +1,26 @@
-# Makefile for Sphinx documentation
-#
+.PHONY:
+init:
+	pip install tox pre-commit
+	pre-commit install
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-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
+.PHONY:
+html:
+	tox run -e html
 
-# 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:
+lint:
+	tox run -e lint,linkcheck
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+.PHONY:
+add-author:
+	tox run -e add-author
 
-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"
+.PHONY:
+sync-authors:
+	tox run -e sync-authors
 
+.PHONY:
 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."
+	rm -rf _build
+	rm -rf .technote
+	rm -rf .tox

README.rst

@@ -1,52 +1,52 @@
-######################################################
-SQR-000 The LSST DM Technical Note Publishing Platform
-######################################################
+.. image:: https://img.shields.io/badge/-lsst.io-brightgreen.svg
+   :target: https://sqr-000.lsst.io/
+.. image:: https://github.com/lsst-sqre/sqr-000/workflows/CI/badge.svg
+   :target: https://github.com/lsst-sqre/sqr-000/actions/
+.. image:: https://zenodo.org/badge/doi/10.5281/zenodo.34154.svg
+   :target: http://dx.doi.org/10.5281/zenodo.34154
 
-SQR-000: The LSST DM Technical Note Publishing Platform
+##############################################
+The LSST DM Technical Note Publishing Platform
+##############################################
 
-View this technote at http://sqr-000.lsst.io
+SQR-000
+=======
 
-.. image:: https://zenodo.org/badge/doi/10.5281/zenodo.34154.svg
-   :target: http://dx.doi.org/10.5281/zenodo.34154
+SQR-000: The LSST DM Technical Note Publishing Platform
+
+**Links:**
 
-.. image:: https://img.shields.io/travis/lsst-sqre/sqr-000.svg
+- Publication URL: https://sqr-000.lsst.io/
+- Alternative editions: https://sqr-000.lsst.io//v
+- GitHub repository: https://github.com/lsst-sqre/sqr-000
+- Build system: https://github.com/lsst-sqre/sqr-000/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-sqre/sqr-000
    cd sqr-000
-   pip install -r requirements.txt
+   make init
    make html
 
-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.
-A good primer on reStructuredText is available at http://docs.lsst.codes/en/latest/development/docs/rst_styleguide.html
-
-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 http://sqr-000.lsst.io will be automatically rebuilt whenever you push your changes to the ``master`` branch on `GitHub <https://github.com/lsst-sqre/sqr-000>`_.
+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``.
 
-Updating metadata
-=================
-
-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.
+The built technote is located at ``_build/html/index.html``.
 
-****
+Publishing changes to the web
+=============================
 
-Copyright 2015 AURA/LSST
+This technote is published to https://sqr-000.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://sqr-000.lsst.io//v.
 
-This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/.
+Editing this technical note
+===========================
 
-.. _Sphinx: http://sphinx-doc.org
+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,22 +1,4 @@
-#!/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 os
-from documenteer.sphinxconfig.technoteconf import configure_technote
-
-# 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)
-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)
+from documenteer.conf.technote import *  # noqa F401 F403

index.rst

@@ -1,11 +1,15 @@
-:tocdepth: 1
+##############################################
+The LSST DM Technical Note Publishing Platform
+##############################################
 
-Technical notes (hereafter, *technotes*) are web-native documents that give `LSST Data Management (DM) <http://dm.lsst.org>`_ staff a standardized, yet flexible, platform to communicate their work.
-Technotes are written in reStructuredText_, version controlled on GitHub_, built with the same stack as DM's software documentation, and made universally citeable with `digital object identifiers (DOIs) <https://en.wikipedia.org/wiki/Digital_object_identifier>`_ provided through Zenodo_.
+.. abstract::
+
+   Technical notes (technotes) are web-native documents that give LSST Data Management staff a standardized, yet flexible, platform to communicate their work.
+   Technotes are written in reStructuredText, version controlled on GitHub, build with the same stack as DM's software documentation, and made universally citeable with digitial object identifiers (DOIs) provided through Zenodo.
 
 This document describes the Technote platform and will be updated as the platform evolves.
 
-DM team members can create a new technote today by following the instructions at https://github.com/lsst-sqre/lsst-technote-bootstrap.
+DM team members can create a new technote today by following the instructions in the `DM Developer Guide <https://developer.lsst.io/project-docs/technotes.html>`__.
 
 We currently use two technote series. The :abbr:`DMTN (Data Management Technote)` is for general use within Data Management.
 The :abbr:`SQR (SQuaRE Technote)` technote series is used for SQuaRE science quality verification and infrastructure work.
@@ -34,7 +38,7 @@ For authors, the editing and version control experience is also clumsy from the
 In the fall of 2015, we experimented with moving several DM design documents from Word documents stored on Docushare_ to documents that are written in reStructuredText_, built with Sphinx_, hosted on GitHub_, and deployed to the web with `Read the Docs`_.
 The impetus behind the transition was that documents written in plain text and hosted on GitHub were far more likely to be kept up-to-date by DM developers.
 
-Technotes were thus built on the same technology stack as the reStructuredText_-based design documents, but re-purposed for general use by DM team members.\ [#]_ 
+Technotes were thus built on the same technology stack as the reStructuredText_-based design documents, but re-purposed for general use by DM team members.\ [#]_
 
 .. [#] In fact, this technote applies equally to describing the new reStructuredText_-based design document platform as it does the technote platform. The only meaningful difference is that design documents must be approved by a control board, and are ultimately deposited in LSST's Docushare_.
 
@@ -226,7 +230,7 @@ series_number:
 
 doc_id:
    **Planned for deprecation.** This is a string that joins ``series`` and ``serial_number`` with a dash.
-    
+
    Example:
 
    .. code-block:: yaml
@@ -320,7 +324,7 @@ abstract:
       abstract: >
                 Write your paragraph
                 here with multiple lines.
-      
+
                 You can have multiple paragraphs too.
 
 url:

requirements.txt

@@ -1 +1 @@
-documenteer[technote]>=0.2.1,<0.3
+documenteer[technote]>=1.0.0a18,<2.0

technote.toml

@@ -0,0 +1,26 @@
+[technote]
+id = "SQR-000"
+series_id = "SQR"
+canonical_url = "https://sqr-000.lsst.io/"
+doi = "10.5281/zenodo.10385499"
+github_url = "https://github.com/lsst-sqre/sqr-000"
+github_default_branch = "main"
+date_created = 2015-11-18
+date_updated = 2015-11-25
+organization.name = "Vera C. Rubin Observatory"
+organization.ror = "https://ror.org/048g3cy84"
+license.id = "CC-BY-4.0"
+
+[[technote.authors]]
+name = {given = "Jonathan", family = "Sick"}
+internal_id = "sickj"
+orcid = "https://orcid.org/0000-0003-3001-676X"
+[[technote.authors.affiliations]]
+name = "Rubin Observatory Project Office"
+internal_id = "RubinObs"
+address = "950 N. Cherry Ave., Tucson, AZ 85719, USA"
+
+[technote.sphinx.linkcheck]
+ignore = [
+    '^https://github.com/lsst-sqre/lsst-technote-bootstrap'
+]