[rnk]

We attempted to deploy Furo for the LLVM Sphinx docs, (llvm/llvm-project#184440), but our sphinx build and publish bot timed out. I replicated the timeout locally, and came up with this PR, which speeds up the build by 10x.

The slowdown occurred because LLVM has a very large global navigation tree. I've seen in the discussions that Furo is intended for "small sites", so perhaps our use case is out of scope, but I thought I'd share anyway.

The bottleneck for us was that each page would reparse the global navtree for every render with beautiful soup. This is kind of O(n^2), it's for each page, parse HTML which has at least as many elements as there are pages, and beautiful soup isn't super fast.

The solution in this PR was to build a sort of shadow DOM with the _NavigationTree and _NavigationElement classes. Rendering the final navtree for each page is a matter of walking this tree, replacing the HTML elements that vary (CSS class, href, etc), and concatenating the rest of the HTML which does not vary between pages.

My initial thought was to use a templating engine to substitute in the parts that vary without parsing HTML, but that ended up being slower.

I synthesized a project generation benchmark, with a hidden toctree containing N pages, and got these numbers before and after this change:

N=100: 1.85s -> 0.94s
N=200: 5.41s -> 1.45s
N=400: 18.82s -> 2.96s
N=800: 75.43s -> 7.83s

That is roughly a 10x speedup in project generation time for the large-navigation case. This change allowed me to finish LLVM's 1,233 page doc build in 1:27.47, instead of hitting my local 10min timeout.

The code is LLM-generated and the PR description is not. I'm happy to try to tune it up or reduce scope to make it fit better. I think the general idea of a custom tree of navigation elements does make sense. Thanks for the theme, and I appreciate any time you spend reviewing this PR. 🙏

[pradyunsg]

OK, this is very cool and I need to poke around with this to understand this enough to maintain it!

[rnk]

OK, this is very cool and I need to poke around with this to understand this enough to maintain it!

Thanks for looking! I should probably put more effort into improving it, I think there are many simplification opportunities. I kind of rushed to send this in the moment, more because the 10x speed achievement felt impressive at the time. While proving a concept is interesting, maintenance cost probably matters more.

The urgency on my side went down since AMD removed their instruction set definitions from our docs, greatly reducing the size of the doc build, so we finished our Furo migration: llvm/llvm-project#211993

Now it's just a matter of optimizing doc build time, which I still care about, but not quite as much.