Merge pull request #234 from lsst/tickets/DM-42142

DM-42142: Release new Markdown and reStructuredText technote templates

.github/workflows/ci.yaml

@@ -41,8 +41,8 @@ jobs:
       - name: Check templates
         run: |
           templatekit check \
-            --ignore "project_templates/technote_rst_early_adopter/testn-000/technote.toml" \
-            --ignore "project_templates/technote_md_early_adopter/testn-000/technote.toml"
+            --ignore "project_templates/technote_rst/testn-000/technote.toml" \
+            --ignore "project_templates/technote_md/testn-000/technote.toml"
 
       # Test TeX builds only with the latest Python version, since they're
       # fairly heavy-weight and the Python version shouldn't matter.

README.md

@@ -33,8 +33,7 @@ Find these templates in the `project_templates/` directory:
 - [technote_aastex](project_templates/technote_aastex/)
 - [technote_latex](project_templates/technote_latex/)
 - [technote_rst](project_templates/technote_rst/)
-- [technote_md_early_adopter](project_templates/technote_md_early_adopter/)
-- [technote_rst_early_adopter](project_templates/technote_rst_early_adopter/)
+- [technote_md](project_templates/technote_md/)
 - [test_report](project_templates/test_report/)
 
 ## File templates

SConstruct

@@ -6,8 +6,7 @@ SConscript(
         "project_templates/stack_package/SConscript",
         "project_templates/nbreport/SConscript",
         "project_templates/technote_rst/SConscript",
-        "project_templates/technote_md_early_adopter/SConscript",
-        "project_templates/technote_rst_early_adopter/SConscript",
+        "project_templates/technote_md/SConscript",
         "project_templates/technote_latex/SConscript",
         "project_templates/technote_aastex/SConscript",
         "project_templates/technote_adasstex/SConscript",

project_templates/technote_md_early_adopter/CHANGELOG.md → project_templates/technote_md/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change log
 
+## 2023-12-17
+
+- The new Markdown technote template is now generally available.
+
 ## 2023-11-01
 
 - Created the `technote_md_early_adopter` template based on the `technote_rst_early_adopter` template.

project_templates/technote_md_early_adopter/templatekit.yaml → project_templates/technote_md/templatekit.yaml

@@ -1,4 +1,4 @@
-name: "Technote (Markdown) Early Adopter"
+name: "Technote (Markdown)"
 group: "Documents"
 dialog_title: "Create an MD technote"
 dialog_fields:

project_templates/technote_rst_early_adopter/testn-000/Makefile → project_templates/technote_md/testn-000/Makefile

@@ -9,7 +9,7 @@ html:
 
 .PHONY:
 lint:
-	tox run -e lint,link-check
+	tox run -e lint,linkcheck
 
 .PHONY:
 add-author:

project_templates/technote_rst_early_adopter/testn-000/technote.toml → project_templates/technote_md/testn-000/technote.toml

@@ -4,7 +4,7 @@ series_id = "TESTN"
 canonical_url = "https://testn-000.lsst.io"
 github_url = "https://github.com/lsst/testn-000"
 github_default_branch = "main"
-date_created = 2023-12-12T21:55:58Z
+date_created = 2023-12-17T22:34:53Z
 organization.name = "Vera C. Rubin Observatory"
 organization.ror = "https://ror.org/048g3cy84"
 license.id = "CC-BY-4.0"

project_templates/technote_md_early_adopter/{{cookiecutter.repo_name}}/Makefile → project_templates/technote_md/{{cookiecutter.repo_name}}/Makefile

@@ -9,7 +9,7 @@ html:
 
 .PHONY:
 lint:
-	tox run -e lint,link-check
+	tox run -e lint,linkcheck
 
 .PHONY:
 add-author:

project_templates/technote_rst/CHANGELOG.md

@@ -1,52 +1,11 @@
 # Change log
 
-## 2021-05-13
+## 2023-12-17
 
-- The `.gitattributes` file now helps suppress the vendored bibtex files from [GitHub pull requests and linguist stats](https://docs.github.com/en/github/administering-a-repository/customizing-how-changed-files-appear-on-github).
+- The new reStructuredText technote template is now generally available.
 
-## 2020-12-10
+## 2023-10-13
 
-- The RTN technote series is now hosted in the "lsst" GitHub organization.
-
-## 2020-06-04
-
-- Switch to GitHub Actions for continuous integration and deployment, replacing Travis CI.
-
-## 2020-05-25
-
-- Add support for the RTN technote series for operations.
-
-## 2019-11-03
-
-- Update to the current versions of Documenteer, >=0.5.4, <0.6.
-
-## 2019-10-21
-
-- Fix support for the TSTN series.
-
-## 2019-10-08
-
-- Template variables that are inserted into `metadata.yaml` are now fully escaped.
-  This means that titles, authors, and descriptions can have characters like single and double quotes, and backslashes.
-
-## 2019-08-26
-
-- Add support for the Telescope & Site technote series (TSTN).
-
-## 2019-07-29
-
-- Add support for the ITTN technote series for LSST IT.
-
-## 2019-04-17
-
-- Ported from the [lsst-technote-bootstrap](https://github.com/lsst-sqre/lsst-technote-bootstrap) repository.
-  This templates repository replaces that original project and is now the canonical template for Sphinx-based technotes.
-
-- Added the `templatekit.yaml` configuration.
-
-- Adopted the full text of the CC-BY license so that GitHub's licensee can detect the license for our technotes.
-
-- Adopted the project-standard [COPYRIGHT file](https://developer.lsst.io/legal/copyright-overview.html).
-
-- Switched to [LTD Conveyor](https://ltd-conveyor.lsst.io) as the upload client for LSST the Docs.
-  [LTD Mason](https://ltd-mason.lsst.io) is deprecated.
+- Created the `technote_rst_early_adopter` template based on the `technote_rst` template.
+  This template is intended for early adopters of the new RST-based technote format.
+  It will replace `technote_rst` once both [Documenteer](https://documenteer.lsst.io) and [Technote](https://technote.lsst.io) get 1.0 releases.

project_templates/technote_rst/README.md

@@ -105,12 +105,15 @@ Example: [.github/workflows/ci.yaml](testn-000/.github/workflows/ci.yaml).
 The [GitHub Actions](https://help.github.com/en/actions) configuration file.
 CI is triggered whenever a technote is pushed to GitHub, and is responsible for deploying the technote to LSST the Docs.
 
-### lsstbib/
+### .github/dependabot.yml
 
-Example: [lsstbib](testn-000/lsstbib).
+This file configures [Dependabot](https://dependabot.com) to automatically update the technote's dependencies with pull requests on GitHub.
 
-This directory contains local copies of LSST BibTeX files that are maintained in [lsst-texmf](https://github.com/lsst/lsst-texmf).
-See the README of the generated technote repository for information on how to update these BibTeX files during the lifetime of a technote.
+### .pre-commit-config.yaml
+
+Example: [.pre-commit-config.yaml](testn-000/.pre-commit-config.yaml).
+
+This file configures the [Pre-commit](https://pre-commit.com) hooks that can run to validate and format the content with every commit.
 
 ### conf.py
 
@@ -126,20 +129,11 @@ Example: [COPYRIGHT](testn-000/COPYRIGHT).
 Record copyright claims in this file, one line per institution.
 See the [copyright](../copyright) template and [Copyrights for LSST DM work and the COPYRIGHT file](https://developer.lsst.io/legal/copyright-overview.html).
 
-### index.py
+### index.rst
 
 Example: [index.rst](testn-000/index.rst).
 
 This is the file that your technote's content should go into.
-There are a few caveats:
-
-- Don't add the top-level document title.
-  This is added for you.
-  Add section headers with `=` underscore symbols.
-  See the [headers documentation in the DM ReStructuredText Style Guide](https://developer.lsst.io/restructuredtext/style.html#sections).
-
-- Don't add `toctree` to incorporate additional pages.
-  You can still spread your content across multiple source files by using the [include](http://docutils.sourceforge.net/docs/ref/rst/directives.html#include) directive.
 
 ### LICENSE
 
@@ -152,22 +146,14 @@ See [Licensing LSST DM source code and content](https://developer.lsst.io/legal/
 
 Example: [local.bib](testn-000/local.bib).
 
-Add BibTeX citations to this file that aren't already available in [lsst-texmf](https://lsst-texmf.lsst.io) (the [lsstbib/](#testn-000/local_bib).
+Add BibTeX citations to this file that aren't already available in [lsst-texmf](https://lsst-texmf.lsst.io).
 See the [Updating bibliographies](https://lsst-texmf.lsst.io/developer.html#updating-bibliographies) documentation in lsst-texmf for how to migrate local bibliography data upstream into [lsst-texmf](https://lsst-texmf.lsst.io).
 
 ### Makefile
 
 Example: [Makefile](testn-000/Makefile).
 
-The Makefile runs the local Sphinx build for authors on their local machines, and is also used by the continous integration build (see [.github/workflows/ci.yaml](testn-000/.github/workflows/ci.yaml)).
-
-### metadata.yaml
-
-Example: [metadata.yaml](testn-000/metadata.yaml).
-
-This metadata file is used by [Documenteer](https://documenteer.lsst.io), which runs the Sphinx build itself.
-Editing the values in this file updates the title and author list in the built and published technote.
-See the comments in that file for further information.
+The Makefile runs the local Sphinx build for authors on their local machines, and is also used by the continuous integration build (see [.github/workflows/ci.yaml](testn-000/.github/workflows/ci.yaml)).
 
 ### README.rst
 
@@ -182,3 +168,19 @@ Example: [requirements.txt](testn-000/requirements.txt).
 The `requirements.txt` file defines build dependencies for both authors, on your local system, and for the CI system.
 If your technote requires additional Python Packages and Sphinx extensions to build, add those requirements to this file.
 Generally speaking, the [documenteer](https://documenteer.lsst.io) dependencies only needs to be updated if the build breaks or you need new features from [Documenteer](https://documenteer.lsst.io).
+
+## technote.toml
+
+Example: [technote.toml](testn-000/technote.toml).
+
+This is the configuration file for the technote.
+It contains both metadata about the document (authors, draft/deprecation status, etc.) and configuration for the Sphinx build.
+See the [Documenteer documentation](https://documenteer.lsst.io/technotes/index.html) for details.
+
+## tox.ini
+
+Example: [tox.ini](testtn-000/tox.ini)
+
+This is the [Tox](https://tox.wiki/en/latest/) configuration file.
+Technotes use tox to build the document in an isolated Python environment.
+The Makefile runs the build through tox.

project_templates/technote_rst/SConscript

@@ -1,7 +1,18 @@
 from templatekit.builder import cookiecutter_project_builder
 
 # Run cookiecutter to generate the 'TESTN-000' report
-env = Environment(BUILDERS={'Cookiecutter': cookiecutter_project_builder})
-env.Cookiecutter(AlwaysBuild(Dir('TESTN-000')),
-                 'cookiecutter.json',
-                 cookiecutter_context={'series': 'TESTN'})
+env = Environment(BUILDERS={"Cookiecutter": cookiecutter_project_builder})
+env.Cookiecutter(
+    AlwaysBuild(Dir("TESTN-000")),
+    "cookiecutter.json",
+    cookiecutter_context={
+        "series": "TESTN",
+        "first_author_given": "First",
+        "first_author_family": "Author",
+        "first_author_orcid": "https://orcid.org/0000-0003-3001-676X",
+        "first_author_author_id": "test",
+        "first_author_affil_name": "Rubin Observatory",
+        "first_author_affil_internal_id": "RubinObs",
+        "first_author_affil_address": ("950 N. Cherry Ave., Tucson, AZ 85719, USA",),
+    },
+)

project_templates/technote_rst/cookiecutter.json

@@ -1,5 +1,5 @@
 {
-  "first_author": "First Last",
+  "author_id": "ID from lsst-texmf/etc/authordb.yaml",
   "series": [
     "DMTN",
     "ITTN",
@@ -40,6 +40,12 @@
     "University of Illinois Board of Trustees",
     "University of Washington"
   ],
+  "first_author_given": "",
+  "first_author_family": "",
+  "first_author_orcid": "",
+  "first_author_affil_name": "",
+  "first_author_affil_internal_id": "",
+  "first_author_affil_address": "",
   "_copy_without_render": [
     "*.bib"
   ],

project_templates/technote_rst/templatekit.yaml

@@ -1,4 +1,4 @@
-name: "Technote (reStructuredText)"
+name: "Technote (reStructuredText) Early Adopter"
 group: "Documents"
 dialog_title: "Create an rst technote"
 dialog_fields:
@@ -12,6 +12,11 @@ dialog_fields:
     hint: "You can use reStructuredText here."
     component: "textarea"
     placeholder: ""
+  - key: "author_id"
+    label: "First author's ID"
+    hint: "ID is a key from lsst-texmf's authordb.yaml (http://ls.st/uyr)"
+    component: "text"
+    placeholder: ""
   - label: "Series"
     component: "select"
     preset_options:

project_templates/technote_rst/testn-000/.gitignore

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

project_templates/technote_rst/testn-000/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