Add JARACO_PACKAGING_SPHINX_WHEEL

README.rst

@@ -38,6 +38,11 @@ To enable, include 'jaraco.packaging' in your requirements and add
 
     extensions=['jaraco.packaging.sphinx']
 
+The extension by default builds the project in an isolated environment in
+order to extract the metadata. If you need to build the documentation offline,
+you can provide an already built wheel by setting the environment variable
+``JARACO_PACKAGING_SPHINX_WHEEL`` to the path of the existing wheel.
+
 make-tree
 =========
 

conftest.py

@@ -0,0 +1,14 @@
+import subprocess
+
+import pytest
+
+
+@pytest.fixture
+def static_wheel(tmp_path, monkeypatch):
+    subprocess.check_call(
+        ['pip', 'download', '--no-deps', '--dest', str(tmp_path), 'sampleproject'],
+        stderr=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+    )
+    (wheel,) = tmp_path.iterdir()
+    monkeypatch.setenv('JARACO_PACKAGING_SPHINX_WHEEL', str(wheel))

jaraco/packaging/sphinx.py

@@ -10,6 +10,7 @@
 import subprocess
 
 from build.util import project_wheel_metadata as load_metadata
+from jaraco.context import suppress
 
 try:
     import importlib.metadata as metadata
@@ -29,13 +30,31 @@ def setup(app):
     return dict(version=metadata.version('jaraco.packaging'), parallel_read_safe=True)
 
 
+@suppress(KeyError)
+def _load_metadata_from_wheel():
+    """
+    If indicated by an environment variable, expect the metadata
+    to be present in a wheel and load it from there, avoiding
+    the build process. Ref jaraco/jaraco.packaging#7.
+
+    >>> _load_metadata_from_wheel()
+    >>> getfixture('static_wheel')
+    >>> meta = _load_metadata_from_wheel()
+    >>> meta['Name']
+    'sampleproject'
+    """
+    wheel = os.environ['JARACO_PACKAGING_SPHINX_WHEEL']
+    (dist,) = metadata.distributions(path=[wheel])
+    return dist.metadata
+
+
 def load_config_from_setup(app):
     """
     Replace values in app.config from package metadata
     """
     # for now, assume project root is one level up
     root = os.path.join(app.confdir, '..')
-    meta = load_metadata(root)
+    meta = _load_metadata_from_wheel() or load_metadata(root)
     app.config.project = meta['Name']
     app.config.version = app.config.release = meta['Version']
     app.config.package_url = meta['Home-page']

setup.cfg

@@ -21,6 +21,7 @@ install_requires =
 	importlib_metadata; python_version < "3.8"
 	# virtualenv extra due to pypa/build#266
 	build[virtualenv]
+	jaraco.context
 
 [options.packages.find]
 exclude =