Make htmllive: New docs Makefile target for easier editing

Documentation
1

We’ve added a new make target for the CPython docs, PEPs and devguide to make iterative editing of docs easier: make htmllive

  • make html - build docs as HTML
  • make htmlview - build docs and open static HTML index page in browser
  • :new: make htmllive - build docs, start a server, and when you save the reST pages you are editing, it will automatically rebuild the docs and reload your page in the browser

With the old make html, you need to tab between three windows:

  1. go to IDE, edit files
  2. go to terminal, run make html
  3. go to browser, reload page and check results

When running the new make htmllive it’s just two:

  1. go to IDE, edit files
  2. go to terminal, run make html
  3. go to browser, reload page and check results

Reminder: run make clean venv first to install the dependencies. And for CPython docs, either run make -C Doc <target> from the root or cd Doc first.

Thanks to sphinx-autobuild for enabling this.

Happy documenting!

7 Likes
2

Perhaps the devguide Documentation section should be updated to mention this?

3

Do I understand correctly that when using make htmllive I have to navigate to the local server manually, once? That’s what I experienced when trying this.

4

Good idea, I’ll open a PR, and also add it to the devguide’s CPython docs section.
[Edit: PR at python/devguide#1219]

Note, I didn’t add it to make.bat because I don’t have Windows to test it. Would a Windows user like to add the equivalent commands to make.bat? I’d suggest the devguide first.

That’s right, there’s a link like [sphinx-autobuild] Serving on http://127.0.0.1:8000 to click. There is actually an --open-browser option we can add so the browser opens on first run. Sounds useful, shall we add it?

5

Nice! I adapted this slightly for pdm and added it to cattrs, really useful.

1 Like
6

Just a quick note, it seems the README wasn’t updated with the new target

1 Like