Merge pull request #144 from lsst-sqre/tickets/DM-37007

DM-37007: Add beta technote theme for Rubin based on technote library

.github/workflows/ci-cron.yaml

@@ -19,7 +19,6 @@ jobs:
           - "3.9"
           - "3.10"
         sphinx-version:
-          - "4"
           - "5"
           - "dev"
 
@@ -28,6 +27,21 @@ jobs:
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
+      - uses: actions/setup-node@v3
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Authenticate GitHub Packages
+        run: |
+          echo "//npm.pkg.github.com/:_authToken=${NPM_PKG_TOKEN}" > ~/.npmrc
+        env:
+          NPM_PKG_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: npm install and build
+        run: |
+          npm install
+          npm run build
+
       - name: Run tests in tox
         uses: lsst-sqre/run-tox@v1
         with:
@@ -58,6 +72,21 @@ jobs:
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
+      - uses: actions/setup-node@v3
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Authenticate GitHub Packages
+        run: |
+          echo "//npm.pkg.github.com/:_authToken=${NPM_PKG_TOKEN}" > ~/.npmrc
+        env:
+          NPM_PKG_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: npm install and build
+        run: |
+          npm install
+          npm run build
+
       - name: Build and publish
         uses: lsst-sqre/build-and-publish-to-pypi@v1
         with:

.github/workflows/ci.yaml

@@ -1,31 +1,30 @@
 name: CI
 
-"on":
+'on':
   push:
     branches-ignore:
       # These should always correspond to pull requests, so ignore them for
       # the push trigger and let them be triggered by the pull_request
       # trigger, avoiding running the workflow twice.  This is a minor
       # optimization so there's no need to ensure this is comprehensive.
-      - "dependabot/**"
-      - "renovate/**"
-      - "tickets/**"
-      - "u/**"
+      - 'dependabot/**'
+      - 'renovate/**'
+      - 'tickets/**'
+      - 'u/**'
     tags:
-      - "*"
+      - '*'
   pull_request: {}
 
 jobs:
   lint:
-
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
 
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.10"
+          python-version: '3.10'
 
       - name: Run pre-commit
         uses: pre-commit/action@v3.0.0
@@ -36,26 +35,38 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.7"
-          - "3.8"
-          - "3.9"
-          - "3.10"
+          - '3.8'
+          - '3.9'
+          - '3.10'
         sphinx-version:
-          - "2"
-          - "3"
-          - "4"
-          - "5"
+          - '5'
 
     steps:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
+      - uses: actions/setup-node@v3
+        with:
+          cache: 'npm'
+          node-version-file: '.nvmrc'
+
+      - name: Authenticate GitHub Packages
+        run: |
+          echo "//npm.pkg.github.com/:_authToken=${NPM_PKG_TOKEN}" > ~/.npmrc
+        env:
+          NPM_PKG_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: npm install and build
+        run: |
+          npm install
+          npm run build
+
       - name: Run tox
         uses: lsst-sqre/run-tox@v1
         with:
           python-version: ${{ matrix.python-version }}
-          tox-envs: "py-test-sphinx${{ matrix.sphinx-version }},typing-sphinx${{ matrix.sphinx-version }}"
+          tox-envs: 'py-test-sphinx${{ matrix.sphinx-version }},typing-sphinx${{ matrix.sphinx-version }}'
 
   docs:
     runs-on: ubuntu-latest
@@ -71,8 +82,8 @@ jobs:
       - name: Run tox
         uses: lsst-sqre/run-tox@v1
         with:
-          python-version: "3.10"
-          tox-envs: "docs,docs-lint"
+          python-version: '3.10'
+          tox-envs: 'docs,docs-lint'
 
       # Only attempt documentation uploads for tagged releases and pull
       # requests from ticket branches in the same repository.  This avoids
@@ -81,27 +92,36 @@ jobs:
       - name: Upload to LSST the Docs
         uses: lsst-sqre/ltd-upload@v1
         with:
-          project: "documenteer"
-          dir: "docs/_build/html"
+          project: 'documenteer'
+          dir: 'docs/_build/html'
           username: ${{ secrets.LTD_USERNAME }}
           password: ${{ secrets.LTD_PASSWORD }}
         if: >
-          github.event_name != 'pull_request'
-          || startsWith(github.head_ref, 'tickets/')
+          github.event_name != 'pull_request' || startsWith(github.head_ref, 'tickets/')
 
-  pypi:
 
+  pypi:
     runs-on: ubuntu-latest
-    needs: [lint,test,docs]
+    needs: [lint, test, docs]
 
     steps:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
+      - uses: actions/setup-node@v3
+        with:
+          cache: 'npm'
+          node-version-file: '.nvmrc'
+
+      - name: npm install and build
+        run: |
+          npm install
+          npm run build
+
       - name: Build and publish
         uses: lsst-sqre/build-and-publish-to-pypi@v1
         with:
           pypi-token: ${{ secrets.PYPI_SQRE_ADMIN }}
-          python-version: "3.10"
+          python-version: '3.10'
           upload: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') }}

.gitignore

@@ -1,3 +1,6 @@
+# JavaScript
+node_modules/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

.npmrc

@@ -0,0 +1 @@
+@lsst-sqre:registry=https://npm.pkg.github.com/

.nvmrc

@@ -0,0 +1 @@
+v18.12.0

.pre-commit-config.yaml

@@ -36,3 +36,9 @@ repos:
     rev: 6.0.0
     hooks:
       - id: flake8
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: 'v2.7.1'
+    hooks:
+      - id: prettier
+        types_or: [css, scss, javascript]

.prettierignore

@@ -0,0 +1,7 @@
+demo/
+.tox
+*.md
+**/*.md
+src/documenteer/templates/**/*.html
+src/documenteer/assets/static/styles
+src/documenteer/assets/static/scripts

.prettierrc.yaml

@@ -0,0 +1,6 @@
+'endOfLine': 'auto'
+'singleQuote': true
+'tabWidth': 2
+'trailingComma': 'es5'
+'printWidth': 80
+'proseWrap': 'never'

.vscode/tasks.json

@@ -0,0 +1,27 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Demo",
+      "detail": "Build demo technote",
+      "type": "shell",
+      "command": "tox -e demo",
+      "problemMatcher": []
+    },
+    {
+      "type": "npm",
+      "script": "build",
+      "group": "build",
+      "problemMatcher": [],
+      "label": "npm: build",
+      "detail": "Build CSS & JS with webpack"
+    },
+    {
+      "label": "Preview",
+      "detail": "Build CSS, JS and demo technote",
+      "dependsOn": ["npm: build", "Demo"],
+      "dependsOrder": "sequence",
+      "problemMatcher": []
+    }
+  ]
+}

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## Unreleased
+
+- Add a new `documenteer.conf.technotebeta` configuration for [technote](https://technote.lsst.io)-based technotes.
+  These technotes are now themed with Rubin's modern branding.
+- Drop support for Python 3.7.
+- Drop support for Sphinx versions earlier than 5.
+
 ## 0.7.0 (2022-10-20)
 
 - Documenteer provides a new Sphinx configuration profile for general Rubin user guide projects, `documenteer.conf.guide`.

MANIFEST.in

@@ -0,0 +1,3 @@
+graft src/documenteer/assets/styles
+graft src/documenteer/assets/scripts
+graft src/documenteer/assets/rsd-assets

Makefile

@@ -15,3 +15,4 @@ clean:
 	rm -rf .tox
 	rm -rf docs/_build
 	rm -rf docs/dev/api/contents/*.rst
+	make -C demo/rst-technote clean

demo/rst-technote/.gitignore

@@ -0,0 +1 @@
+_build

demo/rst-technote/Makefile

@@ -0,0 +1,3 @@
+.PHONY:
+clean:
+	rm -rf _build

demo/rst-technote/conf.py

@@ -0,0 +1 @@
+from documenteer.conf.technotebeta import *  # noqa F401 F403

demo/rst-technote/index.rst

@@ -0,0 +1,60 @@
+#############
+Demo technote
+#############
+
+.. abstract::
+
+   A *technote* is a web-native single page document that enables rapid technical communication within and across teams.
+
+.. Three alphabets is a good guage for line length. We want to shoot for 2-3 alphabets.
+.. abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
+
+Introduction
+============
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+Method
+======
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+A list:
+
+- First item
+- Second item
+- Third item
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+.. code-block:: python
+   :caption: hello.py
+
+   print("Hello world")
+
+Results
+=======
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+Subsection
+----------
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+Subsubsection
+^^^^^^^^^^^^^
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+Analysis
+========
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+Conclusion
+==========
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.

demo/rst-technote/technote.toml

@@ -0,0 +1,16 @@
+[technote]
+id = "SQR-000"
+series_id = "SQR"
+canonical_url = "https://sqr-000.lsst.io"
+github_url = "https://github.com/lsst-sqre/sqr-000"
+github_default_branch = "master"
+date_created = "2015-11-18"
+date_updated = "2015-11-23"
+version = "1.0.0"
+
+[[technote.authors]]
+name = { given_names = "Jonathan", family_names = "Sick" }
+orcid = "https://orcid.org/0000-0003-3001-676X"
+affiliations = [
+    { name = "Rubin Observatory", ror = "https://ror.org/048g3cy84" }
+]

docs/_rst_epilog.rst

@@ -20,6 +20,7 @@
 .. _`LSST DM Docstring Style Guide`: https://developer.lsst.io/python/style.html
 .. _`LSST DM ReStructuredTextStyle Guide`: https://developer.lsst.io/restructuredtext/style.html
 .. _`LSST DM User Documentation Style Guide`: https://developer.lsst.io/user-docs/index.html
+.. _`pydata-sphinx-theme`:
 .. _`PyData Sphinx Theme`: https://pydata-sphinx-theme.readthedocs.io/en/stable/
 .. _`Sphinx Design`: https://sphinx-design.readthedocs.io/en/latest/index.html
 .. _`MyST`: https://myst-parser.readthedocs.io/en/latest/intro.html
@@ -51,6 +52,7 @@
 .. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
 .. _sphinx_autodoc_typehints: https://github.com/tox-dev/sphinx-autodoc-typehints
 .. _tox: https://tox.wiki/en/latest/
+.. _Technote: https://technote.lsst.io/
 
 .. Internal links