sphinx-autobuild
sphinx-autobuild copied to clipboard
sphinx-doc
Rebuild throttling
It looks like sphinx-autobuild does have some rebuild throttling, i.e. it doesn't rebuild for every character you type.
But I don't see any configuration currently for the time intervals involved?
It would also be interesting to consider configuration for turning off builds e.g. if the change is only adding new-lines/whitespace.
At the extreme, it would also be interesting if you could restrict rebuilds to only some kind of "trigger", like a key-board shortcut. No idea how that could work, but it would be cool.
What I am envisaging is packaging this as an extra in jupyter-book (with a jb live CLI command for firing up), for live book reloads.
In this context, really frequent reloads would probably be unwelcome, especially if it also triggers a re-execution of a Jupyter Notebook!
(although this would also be limited by our jupyter-cache functionality, which only triggers re-execution on code changes, not text 😄)
Thoughts @pradyunsg?
(cc also @choldgraf)
This project only builds when files are modified in the directories that it is "watching". If you modify docs/index.rst, this project will detect that the file was modified and trigger a build based on that change.
Are you looking for more granular control over the delays in builds? If so, in what way do you envision it working?
This project only builds when files are modified...
Yes I know what it does lol
in what way do you envision it working?
Well we can start by exposing the delay option of Server.watch: https://github.com/lepture/python-livereload/blob/f14bd7e1685e7b8ee1906eb391d924e1f46d26d4/livereload/server.py#L219
Given this looks pretty relevant to what we are doing in sphinx-book-theme 😬
:param delay: Delay sending the reload message. Use 'forever' to not send it. This is useful to compile sass files to css, but reload on changed css files then only.
This should be a +3/-3 code change, modifying our calls to server.watch(..., [with builder]) to have delay=args.delay, with --delay's default changing to 3 (which matches the default of python-reload).
And, we'll want to update the documentation (README) to correctly note the new default as well as describe the new behavior.
Narrator: it was not "ez"
[I 200831 01:18:06 watcher:110] Running task: build (delay: 10.0)
+------------------------------- changes detected -------------------------------
| Running Sphinx v3.2.1
| loading pickled environment... done
| building [mo]: targets for 0 po files that are out of date
| building [html]: targets for 0 source files that are out of date
| updating environment: 0 added, 0 changed, 0 removed
| looking for now-outdated files... none found
| no targets are out of date.
| build succeeded.
|
| The HTML pages are in build/docs.
+--------------------------------------------------------------------------------
[I 200831 01:18:08 watcher:110] Running task: build (delay: 10.0)
+------------------------------- changes detected -------------------------------
| Running Sphinx v3.2.1
| loading pickled environment... done
| building [mo]: targets for 0 po files that are out of date
| building [html]: targets for 0 source files that are out of date
| updating environment: 0 added, 0 changed, 0 removed
| looking for now-outdated files... none found
| no targets are out of date.
| build succeeded.
|
| The HTML pages are in build/docs.
+--------------------------------------------------------------------------------
[I 200831 01:18:17 handlers:92] Reload 1 waiters: None
[I 200831 01:18:17 handlers:135] Browser Connected: http://127.0.0.1:8000/
[I 200831 01:18:19 handlers:92] Reload 1 waiters: None
[I 200831 01:18:19 handlers:135] Browser Connected: http://127.0.0.1:8000/
Yea, so, it turns out, livereload does reload_time = max(3 - delay, 1) for some reason. No context provided, it just... does that. :)
I'm borderline in the mood to start shipping livereload.js in this package instead of dealing w/ livereload. OTOH, I did spend all of sunday triaging 900+ notifications, so my brain is very mushy right now. >.<
Uh well. I really don't like my free time: https://github.com/lepture/python-livereload/issues/230
😂 I'm just about pipping you to the post this month:
vs
Don't forget that sphinx-book-theme was before this in the FIFO TODO list 😉 😬
