dev: packaging

tinkering to figure out a good way too encapsulate a foreign pip-incompatible
software library contractually.

In this case the Sphinx theme depends upon a gzip-archive (tarball) software
library of an HTML theme. The HTML theme provides static HTML assets and I
expect them to be present under _static/ in the html builder output directory of
Sphinx. The HTML theme is packaged as a gzip archive and provides a GPG
signature. That's basically the contract. But the contract becomes intransparent
as soon as the HTML assets are treated as part of the Sphinx theme project, so
decompressed and unarchived into the src/ directory of the Sphinx theme and
then handled through the sphinx-build hooks. The signature can't be verified
against single files of the archive since the compressed archive is signed.

Ideally, the archive would be decompressed and unarchived during sphinx-build,
but I'm not really happy with the fact that a temporary directory is needed for
this in order to cache as much as possible, so that decompressing isn't required
upon every built. So within the temporary directory, I would have to keep track
of the hash of the compressed archive in order to know when decompression and
unarchiving is needed again, and to store the decompressed assets. Though event
that is not quite intentful. If the performance of treating the tarball archive
as a virtual filesystem, I'd rather let the HTML theme provide an additional
signature for the tarball archive, that way I can check for the existance of
files in the sphinx-build output directory by comparing against a listing of the
tarball archive, after verifying the checksum of the archive hasn't changed.
That way the contract wouldn't be broken and transparent for the user of this
Sphinx theme.

src/byteb4rb1e/sphinxcontrib/theme/seaharvest/__init__.py

@@ -2,22 +2,79 @@
 Tiara's Sphinx theme reference implementation.
 """
 
+from datclasses import dataclass
 from pathlib import Path
+import pkg_resources
 from sys import version_info as python_version
+import os.path
+from typing import Optional
 
 from sphinx import version_info as sphinx_version
+from sphinx import application
 from sphinx.locale import _
 from sphinx.util.logging import getLogger
 
+from hashlib import sha256
+
+digest = sha256()
+
+zbuf = zlib.decompressobj()
+
+
+re.sub('-*-', '-', re.sub('[^A-Za-z0-9_-]', '-', __name__))
+
+
+with pkg_resources.open_binary(
+    __name__,
+    '_vendor/html-theme-seaharvest-1.0.0.tar.gz'
+) as fh:
+
+    while True:
+        buf = fh.read(8096)
+        if not buf: break
+        digest.update(buf)
+        zbuf.decompress(buf)
+
+digest.update()
+
+
+
+
+@dataclass
+class StaticFilesZip():
+    """
+    """
+    basename: str
+    sha256: str
+
+static_files_archive = StaticFilesArchive(
+    path=,
+    sha256='1234567',
+)
+
+
+
 logger = getLogger(__name__)
 
-def setup(app):
+def setup(app: application.Sphinx):
     """
     """
-    app.require_sphinx('8.0')
+    app.require_sphinx('5.0')
 
-    app.add_html_theme('sphinx-theme-ref', Path(__file__).resolve().parent)
+    rootdir = (Path(__file__) / ('../' * 6))
+    archive = (rootdir / 'vendor/{static_archive_basename}').resolve()
 
-    app.add_js_file('assets/script/theme.js')
+
+    app.add_html_theme(__name__.split('.')[-1], Path(__file__).parent)
+
+    app.add_config_value(
+        'html_static_archive_path',
+        [str(archive)],
+        True
+    )
+
+    app.add_js_file('_static/script/seaharvest.js')
+
+    print(app.config['html_static_archive_path'])
 
     return {'parallel_read_safe': True, 'parallel_write_safe': True}