search

sphinx-doc / sphinx-autobuild

Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a hot-reload web server.
MIT License
523 stars 75 forks source link

Doctrees cache causing build loop #67

Closed cag closed 3 years ago

cag commented 5 years ago

To reproduce, simply instrument a project with the ReadTheDocs Getting Started guide, then try to use sphinx-autobuild . _build/html.

See the documentation about the default behavior for the doctree build output here.

This causes projects to rebuild unnecessarily after the doctrees cache files are generated.

Also, if you force the cache to refresh the environment (for example, with the -E option), the autobuilder will build continuously.

A workaround for now is to also specify the -d option, setting it to _build/doctrees for example.

steve-chavez commented 5 years ago

Running into the same issue when trying to build these docs https://github.com/PostgREST/postgrest-docs, it loops like 6 times making the refresh really slow, also the -d work around didn't do it for me, I ran the command like:

sphinx-autobuild -d _build/doctrees -d _build/.doctrees . _build

@cag Any advice for making the -d option work?

cag commented 5 years ago

@steve-chavez Oddly enough, I ran sphinx-autobuild . _build on postgrest-docs and everything worked fine, with no doctrees being generated at all. Running sphinx-autobuild -d _build/doctrees . _build generates doctrees, but also works fine. This is very strange... I'm not sure why this is happening.

steve-chavez commented 5 years ago

@cag There's a build/.doctrees(notice dot) generated though, also I've noticed that even when doing an ls the autobuild starts with a .git/index.lock changed message, and the --ignore .git/ doesn't seem to be working.

steve-chavez commented 5 years ago

Some sensible defaults would be a good addition to the project. For now I've switched to plain livereload https://livereload.readthedocs.io/en/latest/, the sphinx example is working fine.

aaronraimist commented 5 years ago

and the--ignore .git/ doesn't seem to be working.

I know you found a solution but just adding a note here to say that the --ignore option is looking for either an exact match on the file name or a wildcard card character. So --ignore .git/ would only ignore changes to .git/ itself. --ignore .git/* is what you want.

pradyunsg commented 3 years ago

Interesting! Looks like a reasonable bug to be fixed.

pradyunsg commented 3 years ago

This should be fixed by #88.

Could someone try the current master (pip install https://github.com/GaretJax/sphinx-autobuild/archive/develop.zip) and confirm whether this behavior is now fixed?

pradyunsg commented 3 years ago

Assuming that the silence means that this is fixed. If not, please file a new issue with clear reproduction instructions. :)