diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..696b5d7 --- /dev/null +++ b/.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" diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 0000000..a322eed --- /dev/null +++ b/.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 }} diff --git a/.gitignore b/.gitignore index e35d885..da408c0 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,5 @@ -_build +_build/ +.technote/ +.tox/ +venv/ +.venv/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..88db007 --- /dev/null +++ b/.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 diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 55c7fd1..0000000 --- a/.travis.yml +++ /dev/null @@ -1,21 +0,0 @@ -sudo: false -language: python -matrix: - include: - - python: "3.5" - env: LTD_MASON_BUILD=true -install: - - pip install -r requirements.txt - - pip install "ltd-mason>=0.2,<0.3" -script: - - sphinx-build -b html -a -n -W -d _build/doctree . _build/html -after_success: - - ltd-mason-travis --html-dir _build/html -env: - global: - - LTD_MASON_BUILD=false # disable builds in regular text matrix - - LTD_MASON_PRODUCT="sqr-000" - # travis encrypt "LTD_MASON_AWS_ID=... LTD_MASON_AWS_SECRET=..." --add env.global - - secure: "IsqDYlxfcERwrKZ1ABtMEkDmRMK9sTtLa/sFSrt4hSTkk9wl1x7lmao6tHuua8C9jJKL+3dYa7dhKu8eAy3SQXUTAamLZxet8FmjAcO4fajfjVgVVL5ATguxj1yLHFV6RzOuYOjkUTEZ0olcAqh7DGtstCgU9qWmAQvO6gM0zNNYSvQbmSDlVz26xdyM7RPqbEsR2sjNYtMoDEnWOQDGta7Qk2tdMxVF1P+DWkU0BbxExRDCenfJPoYUaGKxNnU0fz9c7ogQ7IFIUNKVqOvLYrGWOJR5xbSq2a1Tbrk4A3PTtsLIbhFXANNkfIwijG7Ew0AIgnhdQJW+Yr63DekeXZHnxq1G17qlrQy8P+Ko6+ZTZcpye81bvJaZhFngwOcU3DMxuBc3rhLL13n43WrWdNElh+B9DrNkpgiC85xNP0PR0lHwkaPJbE2mlsVIprdRvSTHTFkKIro1RdpwKYhgig5ZdM+D2SGCJpVJA7SeFDP7QUf63ug44GsyvUtmINaTrFdcvAdntTmK2BMOj6T05WqNtWVTxw1w2p/Wp8Ue5An8k0RCEg/nenH8CKN8X8yuoy9VzgvbZu9k0XmwCOAUgM4kinFOyYsNAP9LM7CJ0sNu1lnxZvzOvQN4gBTYnyI2iQBLNjBYd+IYcHDfbJ575C3DCMFn97LVeXYO/J0srYw=" - # travis encrypt "LTD_KEEPER_URL=... LTD_KEEPER_USER=... LTD_KEEPER_PASSWORD=..." --add env.global - - secure: "BFlmA3RSOCciFP4x7odshXoxCRTBNl3ckZAVdzEF9nwzyBWVLw/JBRj4U6WwrYvoBYsQiPtzCp6pU+k+SuBt5xCuGGtvn1ZFYRVNWB7bGuCo1nAHgDI94161ckW/dcO6CdCpR0PSnrR3ttbkob7MQrLvYEoEX7rP3D8W6JwdZrMN7fu21OrbNXEdsnhyCKvTuCtigAMngwwKv72RA7XAa9Y2DzxKu/R83zORGHIZiS3Bh9pOKhquDoAo8GzcLzbLCWK3MQfO9RaOps3eSajzWW0oUJMQaTHv0AO6kPOTYkqrgj5+jZiNrvfLgTy6jZspSlGDcSDPDDAnZS63757LN8aKd9SlJ8JqzclZw65FsiMfXNHVhGXgeJfhE+wYNgh/64e7422enPUts3SlWIGPXqNUyBlxjpCG50RhsX1bvAd41x+Sx51dIUKhzQls9RNBY3grGgIIPNrF3Ho0ImXaj+IVQgwBC2ZhABh+VoKWwZt0/FDY1qKKeUjqolAaoJwcdkmwnrI0X7A2uYUm9XwygePTnmrC44Le+jrvNdXS0BrKhS4lSlZDP/53B1Qq3HHyXlVjBbjIFzr376zH7UvdZhNRoyMPXXnFA+0cmSL8KFq9OqerX4QIDNvG1rgyq8iP/a0g0enldD+84VzY4jnHVTccoz7+4Z/x7nI56VsYoqA=" diff --git a/Makefile b/Makefile index 1e7d49a..d01cb27 100644 --- a/Makefile +++ b/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 ' where 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 diff --git a/README.rst b/README.rst index 236eec2..b6e5b5d 100644 --- a/README.rst +++ b/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 `_. +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. diff --git a/conf.py b/conf.py index 90ec90f..f6deb9a 100644 --- a/conf.py +++ b/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 diff --git a/index.rst b/index.rst index 59c149d..353fadf 100644 --- a/index.rst +++ b/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) `_ 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) `_ 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 `__. 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: diff --git a/metadata.yaml b/metadata.yaml deleted file mode 100644 index f8e3fe6..0000000 --- a/metadata.yaml +++ /dev/null @@ -1,54 +0,0 @@ -# Document metadata. metadata.yaml is used by documenteer and other tools -# to build the document and index it. It should be maintained alongside the -# document in git and kept up to date. - -# The series identifier. E.g. SQR, DMTN, LDM, LSE, etc. -series: 'SQR' - -# Document number, as a string. It should be three digits, padded with leading zeros -serial_number: '000' - -# Serial number of the document. E.g. SQR-001 -# NOTE: this field is *planned* for deprecation -doc_id: 'SQR-000' - -# Title of the document, without the series/serial designation -doc_title: 'The LSST DM Technical Note Publishing Platform' - -# Author names, ordered as a list. Each author name should be formatted as 'First Last' -authors: - - 'Jonathan Sick' - -# Current document version -last_revised: '2015-11-23' - -# Version. Use Semvar, e.g., 1.0, including .dev, as necessary -# This version string should correspond to the git tag when the document is published on Zenodo -version: '1.0.0' - -# Digital Object Identifier (DOI). Uncomment if available. -# Keep this DOI updated as new releases are pushed to Zenodo -# doi: 10.5281/zenodo.##### - -# Copyright statement -copyright: '2015, AURA/LSST' - -# Description. A short, 1-2 sentence statemement used by document indices. -description: 'SQR-000: The LSST DM Technical Note Publishing Platform' - -# Abstract, if available -# abstract: > -# Write your paragraph -# here with multiple lines. -# -# You can have multiple paragraphs too. - -# URL where this document is published by Read the Docs. e.g. http://sqr-001.lsst.codes -url: 'http://sqr-000.lsst.io' - -# LSST Docushare URL, if authoritative versions of this are are stored there. -# Leave as an empty string or comment out this key if there is no Docushare URL. -docushare_url: '' - -# GitHub repo URL -github_url: 'https://github.com/lsst-sqre/sqr-000' diff --git a/requirements.txt b/requirements.txt index e29edc2..fc62f98 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1 +1 @@ -documenteer[technote]>=0.2.1,<0.3 +documenteer[technote]>=1.0.0a18,<2.0 diff --git a/technote.toml b/technote.toml new file mode 100644 index 0000000..03d8b5a --- /dev/null +++ b/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' +] diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..210e9ef --- /dev/null +++ b/tox.ini @@ -0,0 +1,29 @@ +[tox] +environments = html +isolated_build = True + +[testenv] +skip_install = true +deps = + -rrequirements.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