Generate a page's navigation links one time and re-use in the navbar / sidebar

[choldgraf]

Context

Right now we have have this function to generate either the navbar navigation or the sidebar navigation:

pydata-sphinx-theme/src/pydata_sphinx_theme/__init__.py

Lines 200 to 209 in 06a35ad

	def generate_nav_html(
	kind, startdepth=None, show_nav_level=1, n_links_before_dropdown=5, **kwargs
	):
	"""
	Return the navigation link structure in HTML. Arguments are passed
	to Sphinx "toctree" function (context["toctree"] below).
	We use beautifulsoup to add the right CSS classes / structure for bootstrap.
	See https://www.sphinx-doc.org/en/master/templating.html#toctree.

And we then re-use it in a few places to do the actual HTML generation:

• In the navbar: https://github.com/pydata/pydata-sphinx-theme/blob/e1d40097204b3617740c9f86112ab0071654d8d2/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-nav.html (two times, once for navbar, once for sidebar)
• In the sidebar: https://github.com/pydata/pydata-sphinx-theme/blob/f57ca0d33fc1ce3d8547a7ff066c7c3fd79af361/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

It seems like this function in particular is time-consuming, and I wonder if this is true regardless of whether it's the sidebar/navbar variety. E.g.:

• Performance regression with v0.10rc2 sidebar links for scipy and arrow docs #855

Idea

If indeed this function is what is causing all of the slowness, how about instead of calling it multiple times, we generate the full HTML structure of the page's toctree one time, we store it in the page context as a beautifulsoup object, and then we re-use that object in building the actual sidebar / navbar HTML.

I think this might be a way to reduce redundant computation and maybe speed things up, it also feels a bit simpler to me.

[choldgraf]

I think that this issue is potentially a simpler way to resolve this problem in the long term:

• Speed up build times significantly by manually generating header navigation links #876

I realized that the proposal here will actually be more complex than I originally thought, because the caption elements aren't generated at the 2nd-and-below level.

• ref: Allow including nested captions in toctree function provided to HTML theme templates sphinx-doc/sphinx#10697