Drop -E from Sphinx call

[mgeier]

A few years ago (see #6966), there was some effort to speed up subsequent builds with different builders by sharing the "doctree" directory.

A remnant of this is still visible since the Sphinx arguments contain -d _build/doctrees.

However, I recently noticed that the Sphinx command now also contain the -E flag, which destroys most of the savings expected from sharing doctrees.

If the -E flag is intentionally used for some reason, the -d argument should probably be removed to avoid confusion.

Details

• Read the Docs project URL: https://readthedocs.org/projects/nbsphinx/
• Build URL (if applicable): https://readthedocs.org/projects/nbsphinx/builds/21799832/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/geier/

Expected Result

Different builders re-use the doctrees, sources are only read for the first build, all subsequent builds are very quick.

Actual Result

Each build reads all source files, not re-using previous doctrees.

[humitos]

Thanks for reporting this. We should probably remove both since there is no shared state between each build anymore.

[humitos]

@mgeier Hrm... Thinking a little more about this. Since we are building the HTML and then the PDF, aren't these toctrees shared between those commands?

[mgeier]

Since we are building the HTML and then the PDF, aren't these toctrees shared between those commands?

I thought that was the intention a few years ago, and this is normally achieved by making sure to specify the same doctree directory with -d, which is the case here.

However, this is all obliterated by the -E flag, which means don't use a saved environment, always read all files.

So even though the doctree directory is technically shared and re-used, because of the -E flag all source files are still read and Sphinx's environment is re-built from scratch.

[humitos]

Thanks for the clarification here.

@stsewd @ericholscher what do you think it's the correct movement here?

• Should we remove both options and keep it working as it's now?
• Should we remove only -E and get the benefits of sharing the parsed doctree between HTML, ePUB and PDF?

Since the root directory is always clean, I think it makes sense to only remove -E which will speed up some projects. In particular, those with many files and building multiple versions.

[stsewd]

+1 on removing the -E option

[ericholscher]

Yea, I think we don't need it anymore since we aren't reusing build directories across builds.