Open Eric-Arellano opened 1 year ago
I also ran into this issue when updating my teams docs site which is very large. I agree it's something the Furo devs should consider. A work around is to use something like the sphinx-remove-toctrees extension which allows you to specify paths for files to remove from the toctree before the sidebar is build.
Thanks, @jonathan343 for pointing me to sphinx-remove-toctrees! I tried out today a similar approach to automatically remove all method pages from the left ToC: https://github.com/Qiskit/qiskit_sphinx_theme/pull/474. That took the build down from 3.5 hours to 1.5 hours.
Unfortunately, 1.5 hours is still slow for us. So we're going to continue with two approaches:
navigation_depth
to our theme that inherits Furo. We probably will stick with -1
for prod builds, but we want to set 1
or 2
in local development builds so that devs are more likely to iterate on the docs.Due to Sphinx inheritance not allowing us to turn off Furo's __init__.py
, it means we need to fully vendor Furo (with attribution per MIT license), then override its Python to add navigation_depth
: https://github.com/Qiskit/qiskit_sphinx_theme/pull/463.
So, it'd still be really helpful to our project if upstream Furo were to have navigation_depth
directly - but I understand if the maintainers don't want to merge.
Last thing I'll comment on (incase you haven't considered) is the -j N
option for sphinx-build
which will:
Distribute the build over N processes in parallel, to make building on multiprocessor machines more effective. Note that not all parts and not all builders of Sphinx can be parallelized. If auto argument is given, Sphinx uses the number of CPUs as N.
Reference: https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-j
This also might help you situation if the hardware you're building on supports it.
Good luck!
What's the behaviour of this if you're on a page that has been trimmed from the sidebar? Is there any indication that you're on such a page?
My understanding is that there isn't, which isn't something I'm keen on. 😅
A work around is to use something like the sphinx-remove-toctrees
FWIW, I wouldn't call it a workaround and would indeed suggest using that as an explicit mechanism that provides much more control than a "chop-off-beyond-depth" approach.
Adding a x-ref to https://github.com/pradyunsg/furo/discussions/289#discussioncomment-1584287 as well.
What's the behaviour of this if you're on a page that has been trimmed from the sidebar? Is there any indication that you're on such a page?
It will highlight the closet parent page possible. E.g. this is on a subpage of Electron
:
I agree that's not a great user experience. Hence, we're planning on still using -1
in production builds. We only want to set 1
or 2
in local docs builds so that devs can build our docs in ~5-10 minutes rather than ~30 when iterating. I'm happy to reword the docs here to emphasize production builds should almost certainly use -1
.
We could even name the variable something like dev_only__navigation_depth
?
Also, this downside could be mitigated by breadcrumbs, which is how we deal with the UX problem in Pytorch, where we currently have the depth at 1
. I intend to add breadcrumbs to qiskit-sphinx-theme
and I'll be glad to upstream this to Furo: https://github.com/pradyunsg/furo/discussions/139#discussioncomment-6104577.
For posterity, Pradyun and I have been investigating the performance issues from the left sidebar more in https://github.com/Qiskit/qiskit_sphinx_theme/issues/328. tl;dr: the latest experiment suggests Furo's slowdown is entirely from the navigation_depth.
I'm proposing reworking this PR to be solely intended to speed up dev builds; it should not be used for prod builds. E.g. we rename the variable to dev_only_navigation_depth
.
FYI here is how Pydata-sphinx-theme sped up this issue just recently: https://github.com/pydata/pydata-sphinx-theme/pull/1609. (Also happy new year! 🥳)
When switching the docs at https://qiskit.org/documentation to Furo, we found that including the full left sidebar is prohibitively expensive:
We are planning to reorganize our site to work around this. We'll stop having a dedicated HTML page for each function and method. That dramatically ameliorates the problem, going from about 3.5 hours to 0.5 hours (vs. 10 minutes for Pytorch with this change.)
However, I realized it's trivial for Furo to allow customizing the
navigation_depth
, similar to themes like RTD. That provides an escape hatch for large projects to use Furo still.A lower
navigation_depth
usually results in a worse user experience, so the new docs emphasize the tradeoffs of this option.Currently not possible for theme inheritance to override
navigation_depth
My first approach was to try to work around this in qiskit-sphinx-theme via https://github.com/Qiskit/qiskit_sphinx_theme/pull/451. I fixed the HTML page size issue by overriding
furo_navigation_toc
.But, I could not fix the build performance because I could not figure out how to turn off Furo's
__init__.py
from calling_compute_navigation_tree
. In Sphinx, when you setinherit = furo
intheme.conf
, that calls all of Furo's extension code from__init__.py
. I could not get monkeypatching to work either so that_compute_navigation_tree
no-oped.