dirty

.gitignore

@@ -1,11 +1,17 @@
 
+.tox/
+
 /dist/
 /build/
-/src/**/*.egg-info
+*.egg-info
-/src/**/*.pyc
+*.pyc
-/src/**/__pycache/
 /.venv/
 /autom4te.cache/
 /config.log
 /config.status
 /configure~
+
+vendor/**/*.tar.gz
+vendor/**/*.tar
+
+test-reports/

Makefile

@@ -1,31 +1,62 @@
-.PHONY: requirements.txt requirements-dev.txt configure Pipfile.lock src/sphinx_theme_ref/assets build
+WEB2_PACKAGE_ID := html-theme-web2-1.0.0
+WEB2_PACKAGE_URL := https://bitbucket.org/byteb4rb1e/html-theme-web2/downloads/$(WEB2_PACKAGE_ID).tar.gz
+PYPKG_DIR := src/byteb4rb1e/sphinxcontrib/theme/web2
+WITH_GPG = $(shell command -v gpg && echo yes)
 
-PKG_BASENAME := sphinx_theme_ref
+PYTHON3=$(if $(wildcard .venv/.*),.venv/bin/python3,python3)
 
-VENDOR_OUTPUT_PATH := $(shell realpath ./src/sphinx_theme_ref/assets)
+VERSION=$(shell $(PYTHON3) -m setuptools_scm)
 
-Pipfile.lock:
+.chore: requirements.txt requirements-dev.txt Pipfile.lock configure
-	.venv/bin/pipenv lock
 
-requirements.txt:
+.clean:
-	.venv/bin/pipenv requirements > requirements.txt
+	rm -rvf dist/ build/
-
-requirements-dev.txt:
-	.venv/bin/pipenv requirements --dev-only > requirements-dev.txt
 
 configure:
 	autoconf
 
-src/sphinx_theme_ref/assets:
+dist: src/
-	rm -r src/$(PKG_BASENAME)/assets
+	$(PYTHON3) -m build
-	make -C vendor/html-theme-ref build/production OUTPUT_PATH=$(VENDOR_OUTPUT_PATH)
 
-# user acceptance testing
+Pipfile.lock:
-uat:
+	pipenv lock
-	trap 'kill 0' SIGINT; \
-	make -C vendor/html-theme-ref watch OUTPUT_PATH=$(VENDOR_OUTPUT_PATH) & \
-	wait
 
-build:
+requirements.txt:
-	.venv/bin/pipenv run build
+	$(PYTHON3) -m pipenv requirements > requirements.txt
 
+requirements-dev.txt:
+	$(PYTHON3) -m pipenv requirements --dev-only > requirements-dev.txt
+
+src src/: $(PYPKG_DIR)/_static_extra.tar $(PYPKG_DIR)/_static_extra.tar.sha256
+
+$(PYPKG_DIR)/_static_extra.tar: vendor/$(WEB2_PACKAGE_ID).tar
+	cp -vf "$<" "$@"
+
+$(PYPKG_DIR)/_static_extra.tar.sha256: vendor/$(WEB2_PACKAGE_ID).tar.sha256
+	cp -vf "$<" "$@"
+
+test-reports test-reports/: test-reports/unit test-reports/integration
+
+test-reports/unit:
+	$(PYTHON3) -m tox -m unit
+
+test-reports/integration:
+	$(PYTHON3) -m tox -m integration
+
+test-reports/audit.json:
+	$(PYTHON3) -m tox -m integration
+
+vendor/$(WEB2_PACKAGE_ID).tar.gz: $(if $(WITH_GPG),vendor/$(WEB2_PACKAGE_ID).tar.gz.asc,)
+	curl -L --fail --output "$@" "$(WEB2_PACKAGE_URL)"
+ifneq ($(WITH_GPG),)
+	gpg --verify "$<" "$@"
+endif
+
+vendor/$(WEB2_PACKAGE_ID).tar.gz.asc:
+	curl -L --fail --output "$@" "$(WEB2_PACKAGE_URL).asc"
+
+vendor/$(WEB2_PACKAGE_ID).tar: vendor/$(WEB2_PACKAGE_ID).tar.gz
+	gzip --decompress --keep --stdout  "$<" > $@
+
+vendor/$(WEB2_PACKAGE_ID).tar.sha256:
+	curl -L --fail --output "vendor/$(WEB2_PACKAGE_ID).tar.sha256" "$(patsubst %.gz,%.sha256,$(WEB2_PACKAGE_URL))"

NOTES

@@ -0,0 +1,11 @@
+
+
+=== Configuration ===
+
+1. Run sh configure
+2. Run make .chore
+
+
+Ḿakefile conventions
+
+abstract targets (e.g. chore, clean, etc.) must be prepended with an underscore.

README.md

@@ -1,4 +1,4 @@
-<a name="tiara-sphinx-theme"></a>
+<a name="byteb4rb1e/sphinxcontrib/theme/web2"></a>
 # Tiara's Sphinx Theme Reference Implementation
 
 > 🛌 **NOTICE:** This project is taking a naap. It depends upon 

docs/Makefile

@@ -0,0 +1,2 @@
+$(patsubst %.puml,%.png,$(wildcard **/*.puml)):
+	plantuml "$$(echo "$@" | sed 's|.png$$|.puml|')"

docs/diagrams/workflow.puml

@@ -0,0 +1,32 @@
+@startuml
+package "Vendor Source" {
+  [WEB2_PACKAGE_URL] --> [vendor/html-theme-web2-1.0.0.tar.gz]
+  [vendor/html-theme-web2-1.0.0.tar.gz] --> [vendor/html-theme-web2-1.0.0.tar]
+  [vendor/html-theme-web2-1.0.0.tar.gz.asc] --> [vendor/html-theme-web2-1.0.0.tar.gz] : GPG verify
+}
+
+package "Python Project" {
+  [vendor/html-theme-web2-1.0.0.tar] --> [src/byteb4rb1e/sphinxcontrib/theme/web2/html-theme-web2.tar] : cp
+  [src/byteb4rb1e/sphinxcontrib/theme/web2/html-theme-web2.tar] ... [src/...]
+  [src/...] --> [dist] : build
+  [configure] --> [configure] : autoconf
+  [requirements.txt] <-- [Pipfile.lock]
+  [requirements-dev.txt] <-- [Pipfile.lock]
+}
+
+package "Testing" {
+  [src/...] --> [test-reports/unit] : tox -m unit
+  [src/...] --> [test-reports/integration] : tox -m integration
+  [src/...] --> [test-reports/audit.json] : tox -m integration
+}
+
+note right of [WEB2_PACKAGE_URL]
+  HTML theme tarball is fetched
+  as a compressed artifact
+end note
+
+note right of [src/...]
+  Contains Python package source
+  and consumes the integrated theme
+end note
+@enduml

pyproject.toml

@@ -12,7 +12,7 @@ description = "Functional theme for Sphinx documentation generator"
 authors = [
     { name = "Tiara Rodney", email = "tiara.rodney@administratrix.de" }
 ]
-license = { file = "LICENSE" }
+license-files = ["LICENSE"]
 readme = "README.md"
 classifiers = [
   "Development Status :: 1 - Planning",
@@ -31,14 +31,18 @@ classifiers = [
   "Topic :: Software Development :: Documentation",
 ]
 dependencies = [
-  "sphinx >= 8.0,<9.0",
+  "sphinx >= 5.0"
 ]
 dynamic = ["version"]
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 
 [project.entry-points."sphinx.html_themes"]
 web2 = "byteb4rb1e.sphinxcontrib.theme.web2"
 
+[tool.setuptools.package-data]
+# relative to root dir of package, NOT repository
+"byteb4rb1e.sphinxcontrib.theme.web2" = ["*.tar", "*.tar.sha256"]
+
 [project.urls]
 Bitbucket = "https://bitbucket.org/byteb4rb1e/sphinxcontrib-theme-seaharvest"
 GitHub = "https://github.com/ByteB4rb1e/sphinxcontrib-theme-seaharvest"

src/byteb4rb1e/sphinxcontrib/theme/web2/.gitignore

@@ -0,0 +1 @@
+*.tar

src/byteb4rb1e/sphinxcontrib/theme/web2/_static_extra.tar.sha256

@@ -0,0 +1 @@
+63e49714a06c865bf8f15e94f9d514cbcdb9927dc20c748a373e93570c4c8e8b

src/byteb4rb1e/sphinxcontrib/theme/web2/assets/.gitignore

@@ -1,20 +0,0 @@
-# generated by Tiara's HTML Theming Reference Implementation
-#
-# this .gitignore serves the purpose of allowing wrapping projects, that
-# generate this project's assets dynamically, not having to worry about
-# auxiliary debugging assets polution. The file is supposed to be copied by
-# webpack into the output directory, so the globbing patterns shouldn't match
-# the current directory. That's why it's called `gitignore` instead of
-# `.gitignore` so that it isn't actually being picked up by git. webpack should
-# rewrite the basename.
-#
-# Depending on your level of paranoia towards breaking changes in dependencies
-# with no access to working versions, you can either choose to ignore the entire
-# directory and generate HTML theme assets just-in-time, or commit them as
-# static assets. I'm running registry proxies as pull-through mirrors locally,
-# that I back up regularly, to keep my paranoia at bay. That way, I can.just
-# gitignore the directory and generate all assets dynamically.
-*
-!/.gitignore
-*.ts
-*.map

tests/integration/byteb4rb1e/sphinxcontrib/theme/web2/test_sphinx_theme.py

@@ -0,0 +1,5 @@
+
+
+def test_default():
+    """
+    """

tests/unit/byteb4rb1e/sphinxcontrib/theme/web2/test_unarchive.py

@@ -0,0 +1,3 @@
+def test_default():
+    """
+    """

tox.ini

@@ -1,73 +1,67 @@
 [tox]
-skipsdist = true
+requires = 
-maxversion = 3.11.0
+    tox>=4.19
-isolated_build = True
 env_list =
-    static-type-check
+    py3{8-12}-{unit}
+    py3{8-12}-sphinx{5-8}-{integration}
     lint
-    test
+    format
-
 
 [testenv]
-basepython = python3
 deps = 
-    {toxinidir}
+    .
-setenv = PYTHONPATH = {toxinidir}/src
-
 
 [testenv:lint]
-description = lint with pylint
+description = run type check on code base
+labels = static
 deps = 
-    pylint >= 2.12.2, < 3
+    mypy
 commands =
-    python3 -m pylint {toxinidir}/src {posargs}
+    python3 -m mypy src tests --junit-xml test-reports/{env_name}.xml
 
-[testenv:static-type-check]
+[testenv:audit]
-description = static type checking
+description = run type check on code base
+labels = audit
 deps = 
-    mypy >=1.5.1,<2
+    pip-audit
 commands =
-    python3 -m mypy {toxinidir}/src {posargs}
+    pip-audit .
 
-[testenv:test]
+[testenv:format]
-description = test suite with pytest
+description = run type check on code base
+labels = static
 deps = 
+    black
+commands =
+    black --check src tests
+
+[testenv:py3{9-13}-unit]
+description = run type check on code base
+labels = unit
+deps = 
+    {[testenv]deps}
     pytest
-    pytest-cov
 commands =
-    pytest \
+    pytest tests/unit --junitxml=test-reports/{env_name}.xml
-        --junitxml=test-reports/full.xml \
-        --cov-report term \
-        --cov-report html:test-reports/coverage \
-        --cov=wsgirouter \
-        {posargs}
 
-[testenv:build-demo]
+[testenv:py3{9-13}-sphinx{5-7}-integration]
-description = test suite with pytest
+description = run type check on code base
+labels = integration
 deps =
-    sphinx
+    {[testenv]deps}
-    {toxinidir}
+    sphinx5: sphinx>=5.0,<=6.0
+    sphinx6: sphinx>=6.0,<=7.0
+    sphinx7: sphinx>=7.0,<=8.0
+    pytest
 commands =
-    sphinx-build -b html -Dhtml4_writer=0 \
+    pytest tests/integration --junitxml=test-reports/{env_name}.xml
-        -d {envtmpdir}/doctrees demo \
-        build/demo
 
-[testenv:autobuild-demo]
+[testenv:py3{10-13}-sphinx8-integration]
-description = test suite with pytest
+description = run type check on code base
+labels = integration
 deps =
-    sphinx
+    {[testenv]deps}
-    sphinx-autobuild
+    sphinx8: sphinx>=8.0,<=9.0
-    {toxinidir}
+    pytest
 commands =
-    sphinx-autobuild -b html -Dhtml4_writer=0 \
+    pytest tests/integration --junitxml=test-reports/{env_name}.xml
-        -d {envtmpdir}/doctrees demo \
-        --watch src/tiararodneycom_theme \
-        build/demo
-
-[testenv:build-sdist]
-description = build and package
-deps = 
-    build >= 0.5.1, < 1
-commands =
-    python3 -m build --sdist {posargs}
-