Merge pull request #226 from lsst/tickets/DM-41517

DM-41517: Add technote_md_early_adopter template

.github/workflows/ci.yaml

@@ -41,7 +41,8 @@ jobs:
       - name: Check templates
         run: |
           templatekit check \
-            --ignore "project_templates/technote_rst_early_adopter/testn-000/technote.toml"
+            --ignore "project_templates/technote_rst_early_adopter/testn-000/technote.toml" \
+            --ignore "project_templates/technote_md_early_adopter/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,6 +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/)
 - [test_report](project_templates/test_report/)
 

SConstruct

@@ -6,6 +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_latex/SConscript",
         "project_templates/technote_aastex/SConscript",

project_templates/technote_md_early_adopter/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change log
+
+## 2023-11-01
+
+- Created the `technote_md_early_adopter` template based on the `technote_rst_early_adopter` template.
+  This template is intended for early adopters of the new Markdown-based technote format.
+  This template will lose the "early adopter" moniker once both [Documenteer](https://documenteer.lsst.io) and [Technote](https://technote.lsst.io) get 1.0 releases.

project_templates/technote_md_early_adopter/README.md

@@ -0,0 +1,186 @@
+# technote_md
+
+**Rubin technical note repository, based on Markdown and Sphinx.**
+
+This template generates a new technical note (technote) repository based on Sphinx.
+Rubin technotes, in general, let you document technical designs, proposals, product overviews, results of prototyping experiments, and other types of documentation that doesn't fit in either the change-controlled document tree, or in user documentation.
+See [Technotes for stand-alone technical documentation in the Developer Guide](https://developer.lsst.io/project-docs/technotes.html).
+
+Keep in mind that technotes are single-page websites.
+Specifically, don't use `toctree` to create a multi-page site.
+Technotes are constrained to single pages so that they can be archived to DocuShare, and as a result the technote infrastructure is designed specifically to support a single-page site.
+
+## Template variables
+
+### cookiecutter.first_author
+
+The name of the first author, formatted as `First Last`.
+
+Once the technote repository is generated you can add additional authors to the `authors` list in `metadata.yaml`.
+
+### cookiecutter.series
+
+The identifier of the technote series.
+Choose the series that fits the document's purpose or aligns with the organization creating the document:
+
+- `DMTN` for Data Management technical notes. See [DMTN-000](https://dmtn-000.lsst.io).
+- `ITTN` for LSST IT technical notes.
+- `RTN` for Rubin Observatory operations technical notes (all departments).
+- `PSTN` for Project Science Team technical notes.
+- `SMTN` for Simulations Group technical notes. See [SMTN-000](https://smtn-000.lsst.io).
+- `SITCOMTN` for Systems Integration, Testing, and Commissioning notes.
+- `SQR` for SQuaRE technical notes. See [SQR-000](https://sqr-000.lsst.io).
+- `TSTN` for Telescope & Site technical notes.
+- `TESTN` for testing the technical system. *These notes may be purged at any time.*
+
+### cookiecutter.serial_number
+
+The serial number. Use three digits padded with zeros.
+If you are creating a technical note manually with this template, see the [Create a technote](https://developer.lsst.io/project-docs/technotes.html#create-a-technote) instructions for how to determine the serial number.
+
+### cookiecutter.title
+
+The title of the technote.
+
+### cookiecutter.repo_name
+
+The name of the GitHub repository
+Cookiecutter will automatically format this for you based on the [series](#cookiecutter_series) and [serial_number](#cookiecutter_serial_number) information.
+
+### cookiecutter.github_org
+
+The GitHub organization where this technote resides.
+Choose a GitHub organization that matches the [series](#cookiecutter_series):
+
+- `lsst-dm` for the DM DMTN series.
+- `lsst-it` for the ITTN series.
+- `rubin-observatory` for the RTN series.
+- `lsst-sims` for the Simulations Group's SMTN series.
+- `lsst-sitcom` for the SITCOMTN series.
+- `lsst-sqre` for the SQuaRE SQR series.
+- `lsst-tstn` for the TSTN series.
+- `lsst-sqre-testing` for the TESTN series.
+
+### cookiecutter.github_namespace
+
+Allow Cookiecutter to populate this variable.
+
+### cookiecutter.docushare_url
+
+This is the technote's URL in LSST's DocuShare archive.
+Leave empty if the technote hasn't been registered with DocuShare yet (which is currently true in most cases).
+
+### cookiecutter.url
+
+The technote's public URL on LSST the Docs.
+Allow cookiecutter to populate this variable.
+
+### cookiecutter.description
+
+A short description of the technote's content and purpose.
+This description is used in the repository's README and may be used in the abstract in the document itself.
+
+### cookiecutter.copyright_year
+
+The year of the initial copyright claim.
+Cookiecutter will automatically populate the current year.
+
+### cookiecutter.copyright_holder
+
+The initial copyright holder.
+See [Copyrights for LSST DM work and the COPYRIGHT file](https://developer.lsst.io/legal/copyright-overview.html) for more information.
+
+## Examples
+
+### testn-000/
+
+The [testn-000](testn-000) directory is an example of a technote generated from the template defaults.
+
+## Files
+
+### .github/workflows/ci.yaml
+
+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.
+
+### .github/dependabot.yml
+
+This file configures [Dependabot](https://dependabot.com) to automatically update the technote's dependencies with pull requests on GitHub.
+
+### .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
+
+Example: [conf.py](testn-000/conf.py).
+
+The Sphinx configuration file.
+The basic Sphinx configuration comes our Documenteer package, but you can append the [typical configuration variables](http://www.sphinx-doc.org/en/master/usage/configuration.html) to the end of that ``conf.py`` to customize the Sphinx build.
+
+### COPYRIGHT
+
+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.md
+
+Example: [index.md](testn-000/index.md).
+
+This is the file that your technote's content should go into.
+
+### LICENSE
+
+Example: [LICENSE](testn-000/LICENSE).
+
+Generally speaking, LSST documentation is licensed under CC-BY 4.0.
+See [Licensing LSST DM source code and content](https://developer.lsst.io/legal/licensing-overview.html) in the Developer Guide for more information.
+
+### local.bib
+
+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).
+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 continuous integration build (see [.github/workflows/ci.yaml](testn-000/.github/workflows/ci.yaml)).
+
+### README.md
+
+Example: [README.md](testn-000/README.md).
+
+The README advertises the technote to GitHub visitors and provides instructions for authors.
+
+### requirements.txt
+
+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_md_early_adopter/SConscript

@@ -0,0 +1,9 @@
+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"},
+)

project_templates/technote_md_early_adopter/cookiecutter.json

@@ -0,0 +1,50 @@
+{
+  "first_author": "First Last",
+  "series": [
+    "DMTN",
+    "ITTN",
+    "RTN",
+    "PSTN",
+    "SMTN",
+    "SITCOMTN",
+    "SQR",
+    "TSTN",
+    "TESTN"
+  ],
+  "serial_number": "000",
+  "title": "Document Title",
+  "repo_name": "{{ cookiecutter.series.lower() }}-{{ cookiecutter.serial_number }}",
+  "github_org": [
+    "lsst",
+    "lsst-dm",
+    "lsst-it",
+    "lsst-pst",
+    "lsst-sims",
+    "lsst-sitcom",
+    "lsst-sqre",
+    "lsst-tstn",
+    "lsst-sqre-testing"
+  ],
+  "github_namespace": "{{ cookiecutter.github_org }}/{{ cookiecutter.repo_name }}",
+  "docushare_url": "",
+  "url": "https://{{ cookiecutter.series.lower() }}-{{ cookiecutter.serial_number }}.lsst.io",
+  "description": "A short description of this document",
+  "copyright_year": "{% now 'utc', '%Y' %}",
+  "copyright_holder": [
+    "Association of Universities for Research in Astronomy, Inc. (AURA)",
+    "Brookhaven Science Associates, LLC",
+    "California Institute of Technology",
+    "Fermi Research Alliance, LLC",
+    "The Board of Trustees of the Leland Stanford Junior University, through SLAC National Accelerator Laboratory",
+    "The Trustees of Princeton University",
+    "University of Illinois Board of Trustees",
+    "University of Washington"
+  ],
+  "_copy_without_render": [
+    "*.bib"
+  ],
+  "_extensions": [
+    "jinja2_time.TimeExtension",
+    "templatekit.TemplatekitExtension"
+  ]
+}

project_templates/technote_md_early_adopter/templatekit.yaml

@@ -0,0 +1,66 @@
+name: "Technote (Markdown) Early Adopter"
+group: "Documents"
+dialog_title: "Create an MD technote"
+dialog_fields:
+  - key: "title"
+    label: "Technote title"
+    placeholder: ""
+    hint: "Don't include the document's handle and avoid MD markup."
+    component: "textarea"
+  - key: "description"
+    label: "Abstract or description"
+    hint: "You can use Markdown here."
+    component: "textarea"
+    placeholder: ""
+  - label: "Series"
+    component: "select"
+    preset_options:
+      - label: "DMTN"
+        value: "dmtn"
+        presets:
+          series: "DMTN"
+          github_org: "lsst-dm"
+      - label: "ITTN"
+        value: "ittn"
+        presets:
+          series: "ITTN"
+          github_org: "lsst-it"
+      - label: "PSTN"
+        value: "PSTN"
+        presets:
+          series: "PSTN"
+          github_org: "lsst-pst"
+          org: "PST"
+      - label: "RTN"
+        value: "rtn"
+        presets:
+          series: "RTN"
+          github_org: "lsst"
+      - label: "SITCOMTN"
+        value: "sitcomtn"
+        presets:
+          series: "SITCOMTN"
+          github_org: "lsst-sitcom"
+      - label: "SMTN"
+        value: "smtn"
+        presets:
+          series: "SMTN"
+          github_org: "lsst-sims"
+      - label: "SQR"
+        value: "sqr"
+        presets:
+          series: "SQR"
+          github_org: "lsst-sqre"
+      - label: "TSTN"
+        value: "tstn"
+        presets:
+          series: "TSTN"
+          github_org: "lsst-tstn"
+      - label: "Test"
+        value: "test"
+        presets:
+          series: "TESTN"
+          github_org: "lsst-sqre-testing"
+  - label: "Initial copyright holder"
+    key: "copyright_holder"
+    component: "select"

project_templates/technote_md_early_adopter/testn-000/.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"

project_templates/technote_md_early_adopter/testn-000/.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: testn-000
+    secrets:
+      ltd_username: ${{ secrets.LTD_USERNAME }}
+      ltd_password: ${{ secrets.LTD_PASSWORD }}

project_templates/technote_md_early_adopter/testn-000/.gitignore

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

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

project_templates/technote_md_early_adopter/testn-000/COPYRIGHT

@@ -0,0 +1 @@
+Copyright 2023 Association of Universities for Research in Astronomy, Inc. (AURA)