Add make autobuild to rebuild and reload HTML files in your browser

[hugovk]

Add a make autobuild target to use https://github.com/executablebooks/sphinx-autobuild.

When you run it, it builds the docs and serves them at something like http://127.0.0.1:8000/

You can visit any page, for example http://127.0.0.1:8000/documentation/style-guide.html, and when you edit/save your source .rst file, it will automatically rebuild and update the page in the browser.

This drastically improves the edit/inspect loop. A very nice touch is it will also keep you at the same position in the page.

Compare before:

1. switch to IDE: edit, save
2. switch to prompt: make html
3. switch to browser: reload, inspect
4. repeat

To this PR:

1. switch to IDE: edit, save
2. switch to prompt: make html
3. switch to browser: reload, inspect
4. repeat

We can add the same thing to CPython Docs and PEPs later.

cc @pradyunsg

---

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

[hugovk]

Naming things:

There used to be a make serve in devguide and CPython docs:

devguide/Makefile

Lines 192 to 195 in cd06b15

	.PHONY: serve
	serve:
	@echo "The 'serve' target was removed, use 'htmlview' instead" \
	"(see https://github.com/python/cpython/issues/80510)"

https://github.com/python/cpython/blob/9d4a1a480b65196c3aabbcd2d165d1fb86d0c8e5/Doc/Makefile#L222-L224

But it was removed in favour of make htmlview (python/cpython#32354) because it started a local server and opened the page, and didn't offer much more than htmlview. No rebuilding of docs, and no reloading the page.

I went for make autobuild here because that's what the underlying tool is called, and I think is more descriptive of what's happening. And also to avoid the old name. But happy to bikeshed a bit! 🚲🛖

Pillow uses livehtml for something similar (using livereload). Do other projects have something?

[pradyunsg]

Do other projects have something?

A bunch of projects I'm involved in (like pip, Furo, sphinx-theme-builder etc) use docs-live, which has a nice property of conveying make docs -> make docs-live on autocompletes/shell navigation; for when I goof up.

[ezio-melotti]

We should add a few ignores to this, starting from venv and then adding editor-specific temp/swap files, since these also seems to trigger rebuilds.

[hugovk]

I've added ignores for /.idea/ and /venv/

Anything else?

I could reproduce changes in /.idea/ triggering a rebuild, by doing something in PyCharm. This ignore prevents that 👍

How might /venv/ changes occur when editing? If you have make autobuild in one terminal and then clean or rebuild the venv in another? Under those circumstances, a rebuild may be warranted. In fact, I wonder if the user should even stop autobuild with Ctrl-C and restart...

We should be careful about ignores, we don't want to accidentally ignore things. For example by ignoring plain venv and adding a page like getting-started/using-venv.rst.

[ezio-melotti]

When I was trying autobuild during the sprints I was either installing some additional dependency in the venv or recreating it from scratch from another tab. That triggered several rebuilds and I had to Ctrl+c out of autobuild and restart it manually.

I can add more things to be ignored in a couple of days (I'm currently traveling without my PC). I can create a separate PR for that.

[hugovk]

Sounds good. I wonder if sphinx-autobuild should be ignoring files from .gitignore?

[willingc]

Do other projects have something?

A bunch of projects I'm involved in (like pip, Furo, sphinx-theme-builder etc) use docs-live, which has a nice property of conveying make docs -> make docs-live on autocompletes/shell navigation; for when I goof up.

I don't see any reason that docs-live couldn't be added alongside autobuild in a future PR.

I wonder if sphinx-autobuild should be ignoring files from .gitignore?

Updating .gitignore makes sense to me. I've been meaning to add .venv to the folders ignored.

[pradyunsg]

I wonder if sphinx-autobuild should be ignoring files from .gitignore?

It's a good idea. Could you file an issue for this, over on autobuild?

[hugovk]

✅ sphinx-doc/sphinx-autobuild#140