Rebuild throttling

[chrisjsewell]

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)

[pradyunsg]

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?

[chrisjsewell]

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.

[pradyunsg]

Ah. That's ez. :P

[pradyunsg]

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.

[pradyunsg]

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. >.<

[pradyunsg]

Uh well. I really don't like my free time: lepture/python-livereload#230

[chrisjsewell]

😂 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 😉 😬

[pradyunsg]

Hehe! I haven't pushed a project with >100 commits yet. :P

[chrisjsewell]

good lad!

[AA-Turner]

Duplicated by #174