docbuild: Ignore "source directory has changed"

[mkoeppe]

From #33103 comment:101:

Currently we are not able to warmstart a docbuild from a new source directory (SAGE_ROOT).

To reproduce: After a docbuild in some OLD_SAGE_ROOT (which installs documentation in OLD_SAGE_ROOT/local, create a new worktree or clone of the Sage source and configure it using configure --prefix=OLD_SAGE_ROOT/local. Then the docbuild in the new source tree will show:

[sagemath_doc_html-none] make doc-inventory--reference-references
[sagemath_doc_html-none] cd /workspace/sage && ./sage --docbuild --no-pdf-links reference/references inventory 
[sagemath_doc_html-none] [reference] loading pickled environment... failed
[sagemath_doc_html-none] [reference] failed: source directory has changed

(see also comment in docker/.gitpod.Dockerfile)

This blocks fast incremental builds of the documentation for Gitpod (see #33113) and the per-ticket documentation build (added in #31415).

CC: @tobiasdiez @jhpalmieri @kwankyu

Component: build

Issue created by migration from https://trac.sagemath.org/ticket/33354

[kwankyu]

comment:1

This code in sphinx/environment/__init__.py is relevant:

    def setup(self, app: "Sphinx") -> None:
        """Set up BuildEnvironment object."""
        if self.version and self.version != app.registry.get_envversion(app):
            raise BuildEnvironmentError(__('build environment version not current'))
        elif self.srcdir and self.srcdir != app.srcdir:
            raise BuildEnvironmentError(__('source directory has changed'))

        if self.project:
            app.project.restore(self.project) 

Sphinx rebuilds everything when it detected changes in "environment", in this case, the path to the source doc files.

It seems hard to cheat Sphinx...

[mkoeppe]

Closing in favor of just building in the same directory, as done in #35652