Improve tests and codebase structure to Pep621 (#68)

Co-authored-by: choldgraf <choldgraf@gmail.com>

.git_archival.txt

@@ -0,0 +1,4 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$
+ref-names: $Format:%D$

.github/workflows/release.yml

@@ -0,0 +1,54 @@
+# This will run every time a tag is created and pushed to the repository.
+# It calls our tests workflow via a `workflow_call`, and if tests pass
+# then it triggers our upload to PyPI for a new release.
+name: Make a new release
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+"
+
+jobs:
+  tests:
+    uses: ./.github/workflows/tests.yml
+  dist:
+    name: publish
+    needs: [tests] # require tests to pass before deploy runs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v3
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - name: Build package
+        run: pipx run build
+      - uses: actions/upload-artifact@v3
+        with:
+          path: dist/*
+  upload_pypi:
+    name: publish
+    needs: [dist]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v3
+        with:
+          name: artifact
+          path: dist
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@v1.6.4
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_KEY }}
+  release:
+    needs: [ upload_pypi ]
+    name: Create release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: softprops/action-gh-release@v1
+        with:
+          name: Sphinx thebe ${{ github.ref_name }}
+          prerelease: ${{ contains(github.ref, 'rc') }}
+          generate_release_notes: true

.github/workflows/tests.yml

@@ -2,7 +2,7 @@ name: continuous-integration
 
 on:
   push:
-    branches: [master]
+    branches: [main]
     tags:
       - 'v*'
   pull_request:
@@ -12,19 +12,23 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: [3.7, 3.8, 3.9]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        # Latest and 2 major releases earlier
+        sphinx: [ "~=5.0", "~=7.0" ]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
+        cache: pip
+    - name: Install sphinx-thebe with sphinx ${{ matrix.sphinx }}
       run: |
-        python -m pip install --upgrade pip
-        pip install -e .[sphinx,testing]
+        pip install --upgrade pip
+        pip install --upgrade "Sphinx${{ matrix.sphinx }}" -e .[testing]
     - name: Run tests
       run: |
         pytest

.gitignore

@@ -128,4 +128,6 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
-docs/_build
+### Project specific
+docs/_build
+_version.py

docs/conf.py

@@ -1,22 +1,3 @@
-# -*- coding: utf-8 -*-
-#
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-
 # -- Project information -----------------------------------------------------
 
 project = "Sphinx Thebe"
@@ -100,6 +81,7 @@
     "use_repository_button": True,
     "use_issues_button": True,
     "launch_buttons": {"thebelab": True},
+    "navigation_with_keys": False,  # To prevent an unnecessary warning
 }
 
 # CopyButton configuration

pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sphinx-thebe"
+authors = [
+    { name = "Executable Books Team", email = "executablebooks@gmail.com" },
+]
+maintainers = [
+    # TODO: Add an actual maintainer
+    { name = "Executable Books Team", email = "executablebooks@gmail.com" },
+]
+description = "Integrate interactive code blocks into your documentation with Thebe and Binder."
+readme = "README.md"
+license = "MIT"
+license-files = { paths = ["LICENSE"] }
+requires-python = ">=3.8"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Sphinx :: Extension",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dynamic = ["version"]
+keywords = [
+    "development",
+    "docutils",
+    "sphinx",
+]
+dependencies = [
+    "sphinx>=4",
+]
+
+[project.urls]
+Homepage = "https://github.com/packit/packit"
+
+[project.optional-dependencies]
+sphinx = [
+    "myst-nb",
+    "sphinx-book-theme",
+    "sphinx-copybutton",
+    "sphinx-design",
+]
+testing = [
+    "myst-nb>=1.0.0rc0",
+    "sphinx-copybutton",
+    "sphinx-design",
+    "matplotlib",
+    "pytest",
+    "pytest-regressions",
+    "beautifulsoup4",
+]
+# TODO: Add pre-commits
+dev = [
+    "sphinx-thebe[testing]",
+]
+
+[tool.hatch]
+version.source = "vcs"
+build.hooks.vcs.version-file = "src/sphinx_thebe/_version.py"
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]

readthedocs.yml

@@ -1,6 +1,9 @@
 version: 2
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.12"
 python:
-  version: 3
   install:
       - method: pip
         path: .

sphinx_thebe/__init__.py → src/sphinx_thebe/__init__.py

@@ -9,7 +9,7 @@
 from docutils import nodes
 from sphinx.util import logging
 
-__version__ = "0.2.1"
+from ._version import version as __version__
 
 logger = logging.getLogger(__name__)
 

tests/test_build.py

@@ -19,7 +19,9 @@ class SphinxBuild:
         path_pg_index = path_html.joinpath("index.html")
         path_pg_config = path_html.joinpath("configure.html")
         path_pg_ntbk = path_html.joinpath("examples/notebooks.html")
-        cmd_base = ["sphinx-build", ".", "_build/html", "-a", "-W"]
+        # Test using our documentation but the Alabaster theme
+        # this avoids version pinning clashes with the Book Theme
+        cmd_base = ["sphinx-build", ".", "_build/html", "-D", "html_theme=alabaster", "-a"]
 
         def copy(self, path=None):
             """Copy the specified book to our tests folder for building."""
@@ -34,7 +36,8 @@ def copy(self, path=None):
         def build(self, cmd=None):
             """Build the test book"""
             cmd = [] if cmd is None else cmd
-            run(self.cmd_base + cmd, cwd=self.path_tmp_docs, check=True)
+            output = run(self.cmd_base + cmd, cwd=self.path_tmp_docs, check=True, capture_output=True)
+            self.output = output
 
         def clean(self):
             """Clean the _build folder so files don't clash with new tests."""
@@ -50,6 +53,10 @@ def test_sphinx_thebe(file_regression, sphinx_build):
     # Basic build with defaults
     sphinx_build.build()
 
+    # No build warnings that were raised by sphinx-thebe
+    errors = list(sphinx_build.output.stderr.decode().split("\n"))
+    assert all(["[sphinx-thebe]" not in ii for ii in errors])
+
     # Testing index for base config
     soup_ix = BeautifulSoup(Path(sphinx_build.path_pg_index).read_text(), "html.parser")
     config = soup_ix("script", {"type": "text/x-thebe-config"})

tox.ini

@@ -18,7 +18,7 @@ usedevelop = true
 passenv = TERM  # To make terminal coloring / other variables pass through
 
 [testenv:py{38,39}-sphinx{5,6}]
-extras = sphinx,testing
+extras = testing
 deps =
     sphinx5: sphinx>=5,<6
     sphinx6: sphinx>=6,<7