Opened 4 months ago

Last modified 3 months ago

#33354 new defect

docbuild: Ignore "source directory has changed"

Reported by: mkoeppe Owned by:
Priority: major Milestone: sage-9.7
Component: build Keywords:
Cc: gh-tobiasdiez, jhpalmieri, klee Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges



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).

Change History (2)

comment:1 Changed 4 months ago by klee

This code in sphinx/environment/ 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:

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...

comment:2 Changed 3 months ago by mkoeppe

  • Milestone changed from sage-9.6 to sage-9.7
Note: See TracTickets for help on using tickets.