use the right python "make -C Doc/ serve"

@berkerpeksag

BPO	36329
Nosy	@berkerpeksag, @matrixise, @JulienPalard, @hugovk
PRs	bpo-36329: Declare the version of Python to use for Tools/scripts/serve.py #12385 bpo-36329: Remove 'make -C Doc serve' in favour of 'make -C Doc htmlview' #32354

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-03-17.18:57:38.556>
labels = ['3.11', 'docs']
title = 'use the right python "make -C Doc/ serve"'
updated_at = <Date 2022-04-06.09:32:26.118>
user = 'https://github.com/matrixise'

bugs.python.org fields:

activity = <Date 2022-04-06.09:32:26.118>
actor = 'hugovk'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-03-17.18:57:38.556>
creator = 'matrixise'
dependencies = []
files = []
hgrepos = []
issue_num = 36329
keywords = ['patch']
message_count = 6.0
messages = ['338135', '338195', '341163', '341204', '341211', '416848']
nosy_count = 5.0
nosy_names = ['docs@python', 'berker.peksag', 'matrixise', 'mdk', 'hugovk']
pr_nums = ['12385', '32354']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue36329'
versions = ['Python 3.11']

When serving the documentation with make -C Doc/ serve, we can not specify the path of the python binary.

My use case, I wanted to debug the wsgiref.simple_server method, used by Tools/scripts/serve.py. It's just impossible because we use the default python3 binary from the system or from the virtualenv (pyenv. etc...)

New changeset 09a9f17 by Julien Palard (Stéphane Wirtel) in branch 'master':
bpo-36329: Declare the version of Python to use for Tools/scripts/serve.py (bpo-12385)
09a9f17

Personally, I'd prefer removing the 'serve' target completely. make -C Doc htmlview should already cover most of its use cases. There is no deprecation period needed and there is already a replacement (and IMO better) for it.

@julien

Personally, I'd prefer removing the 'serve' target completely. make -C
Doc htmlview should already cover most of its use cases. There is no
deprecation period needed and there is already a replacement (and IMO
better) for it.

Hi Berker,

When I have read your message, I was surprised because this target
already exists since 2010. It's true we can run the makefile with

my current workflow is

make -C Doc/ venv && make -C Doc/ html serve and open my browser at
http://localhost:8000

but with your suggestion, I think it's better for us and also for the
contributors, just make -C Doc/ venv htmlview. This target will open the
browser with the result of the html build.

So, I have discussed with @julien Palard and he told me that he did not
use the 'serve' target and he discovered the target via my issue.

But there will be an other issue, in the devguide, there is also a
'serve' target in the Makefile with a copy of tools/serve.py.

But there is no htmlview target.

For the moment, we have a common solution for the two project if we want
to show the result to the user, make serve.

We could:

remove 'make serve' from CPython and Devguide
remove tools/serve.py from CPython and Devguide
add htmlview to the DevGuide
update the documentation

+1 for removing the serve.py script and use htmlview.

Yeah, we can add htmlview to devguide. I’ve even added it to Django after I
discovered it in CPython :)

--Berker

I've made PRs for this:

CPython Docs: bpo-36329: Remove 'make -C Doc serve' in favour of 'make -C Doc htmlview' #32354
Devguide: bpo-36329: Replace 'make serve' with 'make htmlview' devguide#826

Also set this bpo for Python 3.11.

For those seeking the old "serve" ability, after make -C Doc html run:

python -m http.server -b localhost -p HTTP/1.1 -d Doc/build/html/ 8088

I use that with a default port forwarding on my ssh session (aka ssh -L 8088:localhost:8088 or equivalent in your .ssh/config) to my development systems.

I rarely have the ability for a development system to run a web browser or automatically tell my desktop browser full of important authentications where to go. In general as risk mitigation, but also in part because I'm happy using remote dev environments and ChromeOS.

We also have make -C Doc htmllive that serves, rebuilds and reloads using https://github.com/sphinx-doc/sphinx-autobuild.

sphinx-autobuild has --port and --host options which could set via SPHINXOPTS (make sure to re-add the existing options if needed) but no --protocol.

cpython/Doc/Makefile

Lines 147 to 150 in d9cfe7e

    
           .PHONY: htmllive 
        
           htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild 
        
           htmllive: SPHINXOPTS = --re-ignore="/venv/" --open-browser --delay 0 
        
           htmllive: html

Navigation Menu

Repository navigation

use the right python "make -C Doc/ serve" #80510

Yeah, we can add htmlview to devguide. I’ve even added it to Django after I
discovered it in CPython :)

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

	.PHONY: htmllive
	htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
	htmllive: SPHINXOPTS = --re-ignore="/venv/" --open-browser --delay 0
	htmllive: html

use the right python "make -C Doc/ serve" #80510

Description

Activity

matrixise commented on Mar 17, 2019

JulienPalard commented on Mar 18, 2019

berkerpeksag commented on Apr 30, 2019

matrixise commented on May 1, 2019

berkerpeksag commented on May 1, 2019

Yeah, we can add htmlview to devguide. I’ve even added it to Django after I discovered it in CPython :)

hugovk commented on Apr 6, 2022

gpshead commented on Mar 29, 2024

hugovk commented on Mar 29, 2024

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Yeah, we can add htmlview to devguide. I’ve even added it to Django after I
discovered it in CPython :)