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

Add support for autobuilding -M within Sphinx #151

Open tim-nordell-nimbelink opened 3 months ago

tim-nordell-nimbelink commented 3 months ago

sphinx-build has a hiddenish entry point (it doesn't show up in sphinx-build --help) that is used for some build targets (see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/cmd/build.py#L381-L384). It's useful to be able to autobuild these, like -M latexpdf, beyond autobuilding the HTML targets. There are PDF viewing programs that will autoreload when the PDF underneath changes, so this can be very useful for previewing the PDF output when one makes changes.

Additionally, the second patch allows multiple file changes to be consolidated into one build invocation of sphinx-build (at least while running with pyinotify installed which is automatically used by the livereload package if present). This can occur when changing branches, for instance. This is especially visible when doing a latexpdf build since it takes quite a bit longer than refreshing individual HTML files and it always fully rebuilds the project instead of individual files like a html build does.

tim-nordell-nimbelink commented 3 months ago

The first patch in this series is probably related to the intent behind the suggestions within #87 although solves it in a different manner that doesn't introduce delays.

tim-nordell-nimbelink commented 2 months ago

Given how -M is implemented I'd prefer to do this avoiding adding -M to argparse here.

I'll look at refactoring this sometime later this week if I get a chance.

I've just pushed an update which removes LiveReload // Tornado in favour of a simpler WebSocket based implementation, so please remove the tornado imports. They do seem a little out of place, though.

I'll take a look at this change.