Merge pull request #6991 from readthedocs/humitos/document-share-sphinx-doctree-flag

Document SHARE_SPHINX_DOCTREE flag

Author: ericholscher

docs/guides/feature-flags.rst

@@ -36,3 +36,11 @@ e.g. python-reno release notes manager is known to do that
 ``USE_TESTING_BUILD_IMAGE``: :featureflags:`USE_TESTING_BUILD_IMAGE`
 
 ``EXTERNAL_VERSION_BUILD``: :featureflags:`EXTERNAL_VERSION_BUILD`
+
+``SHARE_SPHINX_DOCTREE``: :featureflags:`SHARE_SPHINX_DOCTREE`
+
+By default, when Read the Docs runs Sphinx it passes a different output directory for the generated/parsed doctrees
+(the argument ``-d _build/doctrees-{builder}`` is passed to ``sphinx-build``).
+While this is a way to ensure that all the outputs are generated from scratch,
+it may cause your builds to be slow if you have a big set of documentation and builds multiple formats.
+In that case, enabling ``SHARE_SPHINX_DOCTREE`` could help to speed up your builds by sharing the doctree among all the formats.