New pages don't always appear in sidebar unless you make clean-doc and completely rebuild.

[benjamin051000]

When adding a new page in a toctree, sometimes it disappears when navigating around the built doc page.

This is only resolved by running make clean-doc and rebuilding after that (e.g., make run).

I presume this is because all pages need to generate their own sidebar ToC, and when adding a page, only a few pages are rebuilt, so others are not made aware of the new page. That would explain why it doesn't show up all the time.

Is there any easy way to fix this, or at least print a warning that a new page requires a complete rebuild?

[SecondSkoll]

By default sphinx-autobuild only rebuilds pages affected by changes, as you've noted. This helps to minimise processing time, which can be really important for large documentation sets (the largest Canonical documentation set takes ~20 minutes to build on some systems).

We'd need to hook into sphinx-autobuild to provide that warning in the appropriate place for users to really understand this, but we could also just provide some advice on how to build all pages if there are concerns (which just requires the -a option to be passed to sphinx-autobuild).

[medubelko]

Noting here that files generated/copied by custom scriptlets in conf.py are particularly susceptible to the overall regen problem. For my projects I'm considering adding a rebuild-docs command that cleans + builds to provide a completely fresh artifact. Not sure how to account for that with autobuild.

[SecondSkoll]

@medubelko Have you tried the sphinx-autobuild -a option on I referenced above?

[medubelko]

I haven't tested autobuilds against the odd autogen issue, no. I'll try it next time I run into one.