9.1.1: `jaraco.packaging.sphinx` forces build documentation in isolated build env

[kloczek]

Trying to build documetation in build env which is cut off from public network I found that probably jaraco.packaging.sphinx forces build documentation in isolated build env which is created using .whl archived downloaded from pypi. Of course it fails because it is not able to dwnload those .whl archives. More details are in https://github.com/sphinx-doc/sphinx/issues/11048

I'm not sure but looks like solution of this issue could be allow build documentation without isolation (like when build module is used with --no-isolation) if sphinx-build would be executed for exampe with -D jaraco_packaging_sphinx=no-isolation or by some env variable.

[kloczek]

I'm not 100% sure but looks like none of the modules listed in pyproject.toml requires are used on building documentation and forcing build documentation in isolated env is a bit overkill. What was the propose of that approach with forming and use such isolated build env? 🤔

[kloczek]

I made test and after remove use jaraco.packaging.sphinx sphinx ext I was able to build pip-run docmentation

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v5.3.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 2 added, 0 changed, 0 removed
reading sources... [100%] index
/home/tkloczko/rpmbuild/BUILD/pip-run-9.4.0/docs/index.rst:2: ERROR: Undefined substitution referenced: "project".
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-pip-run.3 { history } /home/tkloczko/rpmbuild/BUILD/pip-run-9.4.0/pip_run/deps.py:docstring of pip_run.deps:1: WARNING: py:class reference target not found: types.SimpleNamespace
/home/tkloczko/rpmbuild/BUILD/pip-run-9.4.0/pip_run/deps.py:docstring of pip_run.deps:1: WARNING: py:class reference target not found: contextlib.ContextDecorator
/home/tkloczko/rpmbuild/BUILD/pip-run-9.4.0/pip_run/scripts.py:docstring of pip_run.scripts.DepsReader.load:1: WARNING: py:class reference target not found: pathlib.Path
/home/tkloczko/rpmbuild/BUILD/pip-run-9.4.0/pip_run/scripts.py:docstring of pip_run.scripts.DepsReader.try_read:1: WARNING: py:class reference target not found: pathlib.Path
/home/tkloczko/rpmbuild/BUILD/pip-run-9.4.0/pip_run/scripts.py:docstring of pip_run.scripts.NotebookDepsReader.load:1: WARNING: py:class reference target not found: pathlib.Path
/home/tkloczko/rpmbuild/BUILD/pip-run-9.4.0/pip_run/scripts.py:docstring of pip_run.scripts.SourceDepsReader.load:1: WARNING: py:class reference target not found: pathlib.Path
done
build succeeded, 7 warnings.

I've used quick patch like below

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -4,7 +4,6 @@

 extensions = [
     'sphinx.ext.autodoc',
-    'jaraco.packaging.sphinx',
 ]

 master_doc = "index"
@@ -17,10 +17,6 @@
         using=dict(GH='https://github.com'),
         replace=[
             dict(
-                pattern=r'(Issue #|\B#)(?P<issue>\d+)',
-                url='{package_url}/issues/{issue}',
-            ),
-            dict(
                 pattern=r'(?m:^((?P<scm_version>v?\d+(\.\d+){1,2}))\n[-=]+\n)',
                 with_scm='{text}\n{rev[timestamp]:%d %b %Y}\n',
             ),

[kloczek]

IMO performing documentation build by default in isolated env is really not necessary. Using such procedure should be only optional.

[jaraco]

This is a dupe of #7.