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

Respond by rebuilding just the modified file(s) #146

Open smontanaro opened 5 months ago

smontanaro commented 5 months ago

This might be related to #118, not sure. I don't really know how sphinx-autobuild works at the low level. Let me describe my scenario and someone more knowledgeable can decide.

I'm trying to help reduce dangling references in the main Python docs. I run make htmllive in the Doc directory and it does its thing. I can view the file I'm working on to see my changes in near realtime. As I work on a particular .rst file, it would be nice if, whenever I saved it, sphinx only reprocessed that one file. I'm running sphinx in nitpicky mode, and it appears to reprocess all files under the Doc directory, spewing thousands of nitpick warnings. Consequently, I can't easily see if the changes I've made to that one file have had a positive effect on the number of warnings for that file. That extra reprocessing seems to also make it take much longer for the generated HTML file to be available for viewing through the web.

aeisenbarth commented 3 weeks ago

Just to put it into perspective: I have a project where a full documentation build takes 30 minutes!

When automated rebuilding is triggered by incremental changes, it does not scale unless it rebuilds only the incremental changes.

Big projects would benefit a lot from shorter feedback cycles. As a work-around, I have to add the desired file paths into conf.py include_patterns or edit all toctrees and remove all links that are not relevant for what I am currently working on.