[Django] #37157: Add "htmllive" for docs development (sphinx-autobuild)

[Django]

#37157: Add "htmllive" for docs development (sphinx-autobuild)
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 6.0 | Severity: Normal
Keywords: sphinx | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
CPython's docs Makefile includes an
[https://github.com/python/cpython/blob/e60c42dc3f5a8dd9b10bc9a8a028ef2765469650/Doc/Makefile#L156-L159
"htmllive"] target that's ''extremely'' helpful while working on docs. It:
- Builds the docs
- Opens a web browser on the local docs build (like Django's "make
htmlview")
- Watches the docs source and rebuilds after any changes
- Hot reloads updated pages

All of this is via [https://github.com/sphinx-doc/sphinx-autobuild sphinx-
autobuild].

We should borrow that "htmllive" target for Django's docs/Makefile.

(I haven't investigated whether sphinx-autobuild works on Windows. If so,
we'd also add it in docs/make.bat.)
--
Ticket URL: <https://code.djangoproject.com/ticket/37157>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#37157: Add "htmllive" for docs development (sphinx-autobuild)
-------------------------------------+-------------------------------------

Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:

Keywords: sphinx | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Mike Edmunds):

* owner: (none) => Mike Edmunds
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/37157#comment:1>

[Django]

#37157: Add "htmllive" for docs development (sphinx-autobuild)
-------------------------------------+-------------------------------------

Reporter: Mike Edmunds | Owner: (none)
Type: | Status: new
Cleanup/optimization |

Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: sphinx | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Mike Edmunds):

* owner: Mike Edmunds => (none)
* status: assigned => new

Comment:

Note that sphinx-autobuild can be used with the existing docs/Makefile by
setting a few variables:

{{{#!shell
python -m pip install sphinx-autobuild
cd docs
SPHINXBUILD=sphinx-autobuild SPHINXOPTS=--open-browser make dirhtml
}}}

You can substitute `make html` or any other html-like target. Set
`SPHINXOPTS='--open-browser --delay 0'` if you want the browser to open
faster.

Something similar should work on Windows with docs/make.bat, which
supports the same variables. (Command syntax is left as an exercise for
the reader.)

Although "htmllive" and "dirhtmllive" Makefile targets would be nice, that
does add a docs dependency on sphinx-autobuild. (Or starts us down the
path of installing dependencies on demand, which is what CPython's
Makefile does.) We might prefer to just mention using sphinx-autobuild as
a tip in the contributor docs.
--
Ticket URL: <https://code.djangoproject.com/ticket/37157#comment:2>

[Django]

#37157: Add "htmllive" for docs development (sphinx-autobuild)
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: sphinx | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia Bidart):

Thank you Mike. I've been using forever `SPHINXOPTS="--port 5555"
SPHINXBUILD=sphinx-autobuild make html` (just because I want my docs in
the 5555 port). In all honesty, I'm not sure we should add this one to the
`Makefile`. It requires a new dependency and we are very careful about
declaring new dependencies in the project.

I wouldn't object to documenting this nicety, though, in the "writing
docs" section. I could accept on that premise, otherwise this is a
(friendly) `wontfix` from my POV.
--
Ticket URL: <https://code.djangoproject.com/ticket/37157#comment:3>

[Django]

#37157: Add "htmllive" for docs development (sphinx-autobuild)
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: sphinx | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Mike Edmunds):

Yeah, I think this would be better as a tip in the docs.

(Can't believe I've been maintaining docs in Sphinx for ~15 years and am
just now learning of sphinx-autobuild 🤯)
--
Ticket URL: <https://code.djangoproject.com/ticket/37157#comment:4>

[Django]

#37157: Add "htmllive" for docs development (sphinx-autobuild)

--------------------------------------+------------------------------------

Reporter: Mike Edmunds | Owner: (none)

Type: Cleanup/optimization | Status: new

Component: Documentation | Version: 6.0
Severity: Normal | Resolution:

Keywords: sphinx | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Natalia Bidart):

* stage: Unreviewed => Accepted

Comment:

Great, accepting as a docs addition.
--
Ticket URL: <https://code.djangoproject.com/ticket/37157#comment:5>