sunpy: Documentation builds are very slow (and caching is not effective)

Describe the performance issue

When i build the docs whether using make html or tox -e build_docs the build deletes previously generated files such as the api files and then have to regenerate them every time. This makes the build very slow. On my machine, it takes 5 mins for make html and half that time with tox.

Do we need to regenerate those files on every build?

To Reproduce

make html

tox -e biuld_docs

Proposed fix

Do not regenerate those files in each build.

About this issue

Original URL
State: closed
Created 8 months ago
Comments: 17 (17 by maintainers)

Most upvoted comments

Some timing runs of just the “writing output” phase of the docs build:

SunPy Sphinx theme
- Build from scratch: 12 minutes, 10 seconds
- Re-build: 12 minutes, 20 seconds
PyData Sphinx theme
- Build from scratch: 5 minutes, 15 seconds
- Re-build: 4 minutes, 55 seconds
default Sphinx theme
- Build from scratch: 70 seconds
- Re-build: 50 seconds

So, indeed, the PyData Sphinx theme takes a long time, but our theme takes over twice as long.

ayshih on Nov 5, 2023

What happens if you just use the plain pydata theme? That would help nail down whether it’s the base theme or something specific to the sunpy one.

wtbarnes on Nov 3, 2023

I can definitely reproduce this now, but I’m befuddled by what has changed. I’m pretty sure it hadn’t been like this a few months ago when I was still working on fixing the inheritance-diagram links. I tried downgrading to Sphinx 5.3.0, and it’s still rebuilding everything. Maybe something having to do with our updated theme?

ayshih on Oct 30, 2023