Merge pull request #13 from lsst-sqre/tickets/DM-33981

[DM-33981] Update build system and packaging

.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,123 @@
+name: Python CI
+
+"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/**"
+    tags:
+      - "*"
+  pull_request: {}
+  schedule:
+    - cron: "0 12 * * 1"
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python:
+          - "3.8"
+          - "3.9"
+          - "3.10"
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Run pre-commit
+        uses: pre-commit/[email protected]
+
+      - name: Install tox
+        run: pip install tox tox-docker
+
+      - name: Cache tox environments
+        id: cache-tox
+        uses: actions/cache@v2
+        with:
+          path: .tox
+          # setup.cfg and pyproject.toml have versioning info that would
+          # impact the tox environment.
+          key: tox-${{ matrix.python }}-${{ hashFiles('pyproject.toml', 'setup.cfg') }}
+
+      - name: Run tox
+        run: tox -e py,typing
+
+  docs:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.10"
+
+      - name: Install Graphviz
+        run: sudo apt-get install graphviz
+
+      - name: Install tox and LTD Conveyor
+        run: pip install tox ltd-conveyor
+
+      - name: Run tox
+        run: tox -e docs
+
+      # Only attempt documentation uploads for tagged releases and pull
+      # requests from ticket branches in the same repository.  This avoids
+      # version clutter in the docs and failures when a PR doesn't have access
+      # to secrets.
+      - name: Upload to LSST the Docs
+        env:
+          LTD_USERNAME: ${{ secrets.LTD_USERNAME }}
+          LTD_PASSWORD: ${{ secrets.LTD_PASSWORD }}
+        run: ltd upload --product templatekit --gh --dir docs/_build/html
+        if: >
+          github.event_name != 'schedule'
+          && (github.event_name != 'pull_request'
+              || startsWith(github.head_ref, 'tickets/'))
+
+  pypi:
+
+    runs-on: ubuntu-latest
+    needs: [test, docs]
+    if: startsWith(github.ref, 'refs/tags/')
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0 # full history for setuptools_scm
+
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade setuptools wheel
+
+      - name: Build
+        run: python setup.py sdist bdist_wheel
+
+      - name: Upload
+        uses: pypa/[email protected]
+        env:
+          user: "__token__"
+          password: ${{ secrets.PYPI_SQRE_ADMIN }}

.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.0.1
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.10.0
+    hooks:
+      - id: isort
+        additional_dependencies:
+          - toml
+
+  - repo: https://github.com/psf/black
+    rev: 22.1.0
+    hooks:
+      - id: black
+
+  - repo: https://gitlab.com/pycqa/flake8
+    rev: 4.0.1
+    hooks:
+      - id: flake8

CHANGELOG.rst

@@ -2,6 +2,13 @@
 Change log
 ##########
 
+0.5.0 (2022-03-15)
+==================
+
+- Update build system to current SQuaRE standards.
+- Add type annotations for all code.
+- Unpin all dependencies for easier use as a library.
+
 0.4.1 (2020-02-26)
 ==================
 
@@ -20,7 +27,7 @@ Change log
 0.3.0 (2019-10-08)
 ==================
 
-- A new Jinja filter, ``escape_yaml_doublequoted``, is available as part of the `templatekit.TemplatekitExtension`.
+- A new Jinja filter, ``escape_yaml_doublequoted``, is available as part of the ``templatekit.TemplatekitExtension``.
   This filter is meant to be used with template variables that are inside double-quoted string fields in a YAML file.
   The filter escapes both double quote characters (``"``) and backslash characters (``\``).
 - There is a new "Template developer" guide, which lists the ``escape_yaml_doublequoted`` filter and provides tips on how to write YAML files in templates.

Makefile

@@ -0,0 +1,5 @@
+.PHONY: init
+init:
+	pip install --upgrade pip tox pre-commit
+	pip install --upgrade -e ".[dev]"
+	pre-commit install

docs/conf.py

@@ -1,13 +1,24 @@
 import os
 import sys
 
-from documenteer.sphinxconfig.utils import form_ltd_edition_name
 import lsst_sphinx_bootstrap_theme
-
+from documenteer.sphinxconfig.utils import form_ltd_edition_name
 
 # Work around Sphinx bug related to large and highly-nested source files
 sys.setrecursionlimit(2000)
 
+# -- Common links and substitutions ---------------------------------------
+
+rst_epilog = """
+
+.. _Cookiecutter: https://cookiecutter.readthedocs.io/en/latest/
+.. _Jinja: http://jinja.pocoo.org
+.. _lsst/templates: https://github.com/lsst/templates
+.. _mypy: http://www.mypy-lang.org
+.. _tox: https://tox.readthedocs.io/en/latest/
+.. _pytest: https://docs.pytest.org/en/latest/
+"""
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -17,42 +28,43 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
-    'sphinx.ext.ifconfig',
-    'sphinx_click.ext',
-    'numpydoc',
-    'sphinx_automodapi.automodapi',
-    'sphinx_automodapi.smart_resolver',
-    'documenteer.sphinxext'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.ifconfig",
+    "sphinx_click.ext",
+    "numpydoc",
+    "sphinx_automodapi.automodapi",
+    "sphinx_automodapi.smart_resolver",
+    "documenteer.sphinxext",
 ]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = 'Templatekit'
-copyright = '2018-2019 Association of Universities for Research in Astronomy'
-author = 'LSST Data Management'
+project = "Templatekit"
+copyright = "2018-2019 Association of Universities for Research in Astronomy"
+author = "LSST Data Management"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-if os.getenv('TRAVIS_BRANCH', default='master') == 'master':
+if os.getenv("TRAVIS_BRANCH", default="master") == "master":
     # Use the current release as the version tag if on master
-    version = 'Current'
+    version = "Current"
     release = version
 else:
     # Use branch name as the version tag
     version = form_ltd_edition_name(
-        git_ref_name=os.getenv('TRAVIS_BRANCH', default='master'))
+        git_ref_name=os.getenv("TRAVIS_BRANCH", default="master")
+    )
     release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -70,63 +82,53 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = [
-    '_build',
-    'README.rst'
-]
+exclude_patterns = ["_build", "README.rst"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # The reST default role cross-links Python (used for this markup: `text`)
-default_role = 'py:obj'
+default_role = "py:obj"
 
 # Intersphinx
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
-    'cookiecutter': ('https://cookiecutter.readthedocs.io/en/latest/', None),
+    "python": ("https://docs.python.org/3/", None),
+    "cookiecutter": ("https://cookiecutter.readthedocs.io/en/latest/", None),
 }
 
-rst_epilog = """
-
-.. _Cookiecutter: https://cookiecutter.readthedocs.io/en/latest/
-.. _Jinja: http://jinja.pocoo.org
-.. _lsst/templates: https://github.com/lsst/templates
-"""
-
 # -- Options for linkcheck builder ----------------------------------------
 
 linkcheck_retries = 2
 
 # -- Options for HTML output ----------------------------------------------
 
 templates_path = [
-    '_templates',
-    lsst_sphinx_bootstrap_theme.get_html_templates_path()
+    "_templates",
+    lsst_sphinx_bootstrap_theme.get_html_templates_path(),
 ]
 
-html_theme = 'lsst_sphinx_bootstrap_theme'
+html_theme = "lsst_sphinx_bootstrap_theme"
 html_theme_path = [lsst_sphinx_bootstrap_theme.get_html_theme_path()]
 
 
 html_context = {
     # Enable "Edit in GitHub" link
-    'display_github': True,
+    "display_github": True,
     # https://{{ github_host|default("github.com") }}/{{ github_user }}/
     #     {{ github_repo }}/blob/
     #     {{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}
-    'github_user': 'lsst-sqre',
-    'github_repo': 'templatekit',
-    'conf_py_path': 'docs/',
+    "github_user": "lsst-sqre",
+    "github_repo": "templatekit",
+    "conf_py_path": "docs/",
     # TRAVIS_BRANCH is available in CI, but master is a safe default
-    'github_version': os.getenv('TRAVIS_BRANCH', default='master') + '/'
+    "github_version": os.getenv("TRAVIS_BRANCH", default="master") + "/",
 }
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {'logotext': project}
+html_theme_options = {"logotext": project}
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".