make htmllive: open browser when ready

[hugovk]

When running make htmllive, this will open the browser when the docs have been built the first time.

It means you don't need to hunt around for the link in:

❯ make htmllive
venv already exists.
To recreate it, remove it first with `make clean-venv'.
Release cycle data generated.
./venv/bin/sphinx-autobuild -b html -d _build/doctrees  --re-ignore="/\.idea/|/venv/" . _build/html
[sphinx-autobuild] > sphinx-build -b html -d _build/doctrees /Users/hugo/github/devguide /Users/hugo/github/devguide/_build/html
Running Sphinx v7.2.6
matplotlib is not installed, social cards will not be generated
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
reading sources...
looking for now-outdated files... none found
no targets are out of date.
Writing redirects...
build succeeded.

The HTML pages are in _build/html.
[I 231129 19:22:56 server:335] Serving on http://127.0.0.1:8000
[I 231129 19:22:56 handlers:62] Start watching changes
[I 231129 19:22:56 handlers:64] Start detecting changes
[I 231129 19:22:58 handlers:135] Browser Connected: http://127.0.0.1:8000/

I'll make the same changes for CPython and PEPs repo afterwards.

---

📚 Documentation preview 📚: https://cpython-devguide--1233.org.readthedocs.build/

[ezio-melotti]

When running make htmllive, this will open the browser when the docs have been built the first time.

So this will build the docs (or possibly rebuild just the files changed since the last time), then open the browser immediately, and then keep refreshing the page without opening new browser tabs, right?

Are there cases where the browser will open before the docs are built? (The --delay suggests there might be, but I haven't tried the PR)

[hugovk]

So this will build the docs (or possibly rebuild just the files changed since the last time), then open the browser immediately, and then keep refreshing the page without opening new browser tabs, right?

Correct, it goes like this:

$ make htmllive
[1. Sphinx builds the docs]
[2. page opened in browser]
[3. user edits and saves]
[4. Sphinx rebuilds the docs]
[5. browser refreshes]
[6. goto 3]

Are there cases where the browser will open before the docs are built? (The --delay suggests there might be, but I haven't tried the PR)

I don't think so, and I've not run into it in a few weeks of testing. The default is 5 seconds, which feels a long time with nothing happening, and then the browser suddenly opening. We can always increase it later if needed.

❯ sphinx-autobuild --help
...
  --open-browser        open the browser after building documentation (default: False)
  --delay DELAY         how long to wait before opening the browser (default: 5)