Repository: readthedocs/readthedocs.org

Issue:
Drop `-E` from Sphinx call
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.


Discussion:
Thanks for reporting this. We should probably remove both since there is no shared state between each build anymore.
@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?
> 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.
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.
+1 on removing the -E option
Yea, I think we don't need it anymore since we aren't reusing build directories across builds. 

Resolving patch:
diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py
--- a/readthedocs/doc_builder/backends/sphinx.py
+++ b/readthedocs/doc_builder/backends/sphinx.py
@@ -295,7 +295,6 @@ def build(self):
         build_command = [
             *self.get_sphinx_cmd(),
             "-T",
-            "-E",
         ]
         if self.config.sphinx.fail_on_warning:
             build_command.extend(["-W", "--keep-going"])
@@ -483,7 +482,6 @@ def build(self):
         self.run(
             *self.get_sphinx_cmd(),
             "-T",
-            "-E",
             "-b",
             self.sphinx_builder,
             "-d",


Test patch:
diff --git a/readthedocs/projects/tests/test_build_tasks.py b/readthedocs/projects/tests/test_build_tasks.py
--- a/readthedocs/projects/tests/test_build_tasks.py
+++ b/readthedocs/projects/tests/test_build_tasks.py
@@ -191,7 +191,6 @@ def test_build_sphinx_formats(self, load_yaml_config, formats, builders):
                 "-m",
                 "sphinx",
                 "-T",
-                "-E",
                 "-b",
                 "html",
                 "-d",
@@ -212,7 +211,6 @@ def test_build_sphinx_formats(self, load_yaml_config, formats, builders):
                     "-m",
                     "sphinx",
                     "-T",
-                    "-E",
                     "-b",
                     builder,
                     "-d",
@@ -829,7 +827,6 @@ def test_build_commands_executed(
                     "-m",
                     "sphinx",
                     "-T",
-                    "-E",
                     "-b",
                     "html",
                     "-d",
@@ -846,7 +843,6 @@ def test_build_commands_executed(
                     "-m",
                     "sphinx",
                     "-T",
-                    "-E",
                     "-b",
                     "readthedocssinglehtmllocalmedia",
                     "-d",
@@ -891,7 +887,6 @@ def test_build_commands_executed(
                     "-m",
                     "sphinx",
                     "-T",
-                    "-E",
                     "-b",
                     "latex",
                     "-d",
@@ -911,7 +906,6 @@ def test_build_commands_executed(
                     "-m",
                     "sphinx",
                     "-T",
-                    "-E",
                     "-b",
                     "epub",
                     "-d",
@@ -1467,7 +1461,6 @@ def test_sphinx_normalized_language(self, load_yaml_config):
                     "-m",
                     "sphinx",
                     "-T",
-                    "-E",
                     "-W",  # fail on warning flag
                     "--keep-going",  # fail on warning flag
                     "-b",
@@ -1506,7 +1499,6 @@ def test_sphinx_fail_on_warning(self, load_yaml_config):
                     "-m",
                     "sphinx",
                     "-T",
-                    "-E",
                     "-W",  # fail on warning flag
                     "--keep-going",  # fail on warning flag
                     "-b",
@@ -1843,7 +1835,6 @@ def test_sphinx_builder(self, load_yaml_config, value, command):
                     "-m",
                     "sphinx",
                     "-T",
-                    "-E",
                     "-b",
                     command,
                     "-d",