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.
Well... I really have to come up with a convention of describing integration of
submodule changes. Feels a bit repetitive to describe what the changes are when
they're already described in the commits of the submodule itself...
temporarily locking to latest version of Sphinx. Will downgrade once stable.
Additionally, removed anything I don't need at the moment. Copied this from an
old theme of mine.
Now, the HTML theme build is daisy-chained to the build of the Sphinx theme,
including a skeleton for watching, which will be part of user-acceptance
testing, which will be sphinx-autobuild building `docs/`.
Sphinx is part of the dependency defined in pyproject.toml, therefore redundant
to explicitly define it in Pipfile, since the project is an editable dependency.
Adding pipenv as a dependency to the pipenv environment itself is admittedly
counter-intuitive, however this gives the advantage of being able to install all
dependencies (including dev-dependencies) via the common and generally available
`pip` package manager interface. The generation of requirements.txt and
requirements-dev.txt is abstracted through the Makefile.
Since the repository is an older attempt at formulating a reference (it was more
of a failed boilerplating attempt). I (just) need to rearrange a couple of
things before being able to integrate the HTML theme reference.
