-
Notifications
You must be signed in to change notification settings - Fork 320
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Expandable sidebar sections with huge sphinx sites (eg large API reference) results in a very slow build #364
Comments
Could you make the api pages orphans, and then manually link to them in the toctree? |
Ref: #321
|
I opened #386 to make this configurable, so at least it's easy to turn off expandable navigation in the sidebar in case you don't want it. In pandas, I solved it for now by turning it off only specifically for the API section of the docs with a small template override: pandas-dev/pandas#40761 But I think the |
Thinking a bit more about the In addition, we would need to instruct autosummary not to include such a toctree. That's probably only possible upstream in sphinx itself. |
I was just playing around with this since the Dask folks just ran into this as well (👋 @jacobtomlinson) EDIT: I just realized that I was encountering an artifact from previous builds, and my nifty suggestion wasn't so good after all 😬 |
I think that I have a fix for this here: #492 |
Hi, I have run into this issue with the sphinx-book-theme here executablebooks/sphinx-book-theme#561 Looking into this, I have come up with the following proposal executablebooks/sphinx-book-theme#561 (comment):
This will require some changes in this repository. I wanted to get a feel for how this would be received if I open a PR:
|
Can you make a clear write-up of the problem that this would resolve? Why does adding a unique CSS class to every sidebar item result in smaller build sizes? I'd recommend writing this up as a separate issue so that it is easier to discuss the pros / cons of the proposal. In my opinion this original issue can be considered resolved now that we have documentation to get around it here: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/configuring.html#navigation-depth |
@choldgraf as requested, I have written this up (hopefully more clearly) into #762 |
sounds good, I will also close this one as resolved via documentation: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/configuring.html#navigation-depth and we can discuss more specific proposals to improve the build times / size in #762 (or other issues) |
Now that the collapsible sections in the sidebar are in master, I am noticing that this gives some challenges in the pandas docs, and especially the API reference part.
If you have a huge site with many pages, the change in #349 has the consequence that each page is now included in the
toctree
(we usecollapse=False
now), which means that 1) the build is much slower and 2) the size of the html build artefact is much bigger.Specifically for the pandas API docs (https://pandas.pydata.org/docs/dev/reference/index.html), we have more than 1000 API pages, and since the docs are built with #349 being merged, the build time went from ~15min to ~55min and the build artifact from 180Mb to 1.1GB. The html of a single page now contains 15,000 lines for the sidebar ..
(aside: we have too many API pages in pandas, as some are identical (duplicated) pages for shared methods accross subclasses, this is something we can improve and deduplicate. But even with less API pages, you will still notice the difference)
Brainstorming some ways this issue could be addressed (in general, and for pandas specifically):
autosummary
automatically adds those pages to the toctree, so they end up in the sidebar, is IMO not really necessary (eg see https://pandas.pydata.org/docs/dev/reference/io.html, all functions are already listed on the page, so that they are also included in the sidebar is a bit duplicative, and it makes the sidebar also very long). But I am not sure how avoid this using sphinx.collapse=True
specifically in the API reference section of the pandas docs. Pandas could do this by overriding the template and depending on the pagename setcollapse
to True or False. Or would there be another way to configure this?The text was updated successfully, but these errors were encountered: