Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Closed
matrixise opened this issue Mar 17, 2019 · 8 comments · Fixed by python/devguide#826
Closed

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

matrixise opened this issue Mar 17, 2019 · 8 comments · Fixed by python/devguide#826
Labels
3.11 only security fixes docs Documentation in the Doc dir

Comments

@matrixise
Copy link
Member

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']
    @matrixise
    Copy link
    Member Author

    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...)

    @matrixise matrixise added 3.8 only security fixes docs Documentation in the Doc dir labels Mar 17, 2019
    @JulienPalard
    Copy link
    Member

    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

    @berkerpeksag
    Copy link
    Member

    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.

    @matrixise
    Copy link
    Member Author

    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.

    @berkerpeksag
    Copy link
    Member

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

    --Berker

    @hugovk
    Copy link
    Member

    hugovk commented Apr 6, 2022 •
    edited by ezio-melotti

    I've made PRs for this:

    Also set this bpo for Python 3.11.

    @hugovk hugovk added 3.11 only security fixes and removed 3.8 only security fixes labels Apr 6, 2022
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @AA-Turner AA-Turner mentioned this issue May 2, 2022
    Closed
    @hugovk hugovk mentioned this issue May 3, 2022
    Merged
    @gpshead
    Copy link
    Member

    gpshead commented Mar 29, 2024

    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.

    @hugovk
    Copy link
    Member

    hugovk commented Mar 29, 2024 •
    edited

    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

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.11 only security fixes docs Documentation in the Doc dir
    Projects
    None yet
    Milestone
    No milestone
    Development

    Successfully merging a pull request may close this issue.

    bpo-36329: Replace 'make serve' with 'make htmlview' hugovk/devguide
    5 participants
    @berkerpeksag @matrixise @gpshead @JulienPalard @hugovk