From 89c6b2b8f615a1c1827a92c4582c213b1a5027fb Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 29 Apr 2022 16:47:26 +0300 Subject: [PATCH] bpo-36329: Remove 'make -C Doc serve' in favour of 'make -C Doc htmlview' (GH-32354) Also updated `make -C htmlview` so it used a full path with `file://`, because the original didn't open the page (macOS). For example: ```sh cd Doc # Doesn't open anything: python3 -c "import webbrowser; webbrowser.open('build/html/index.html')" # Opens the docs page e.g. file:///Users/hugo/github/cpython/Doc/build/html/index.html : python3 -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))" ``` https://bugs.python.org/issue36329 --- Doc/Makefile | 6 +- Doc/library/wsgiref.rst | 70 +++++++++++++++---- Doc/make.bat | 4 +- .../2022-04-06-11-53-41.bpo-36329.EVtAtK.rst | 1 + Tools/scripts/README | 1 - Tools/scripts/serve.py | 36 ---------- 6 files changed, 63 insertions(+), 55 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2022-04-06-11-53-41.bpo-36329.EVtAtK.rst delete mode 100755 Tools/scripts/serve.py diff --git a/Doc/Makefile b/Doc/Makefile index 61a7ce0d098..3a3417bf99a 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -13,7 +13,6 @@ PAPER = SOURCES = DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) SPHINXERRORHANDLING = -W -SERVE_PORT = # Internal variables. PAPEROPT_a4 = -D latex_elements.papersize=a4paper @@ -45,7 +44,6 @@ help: @echo " dist to create a \"dist\" directory with archived docs for download" @echo " suspicious to check for suspicious markup in output text" @echo " check to run a check for frequent markup errors" - @echo " serve to serve the documentation on the localhost (8000)" build: -mkdir -p build @@ -141,7 +139,7 @@ pydoc-topics: build "cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py" htmlview: html - $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')" + $(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))" clean: clean-venv -rm -rf build/* @@ -219,7 +217,7 @@ check: $(SPHINXLINT) ../Misc/NEWS.d/next/ serve: - $(PYTHON) ../Tools/scripts/serve.py build/html $(SERVE_PORT) + @echo "The serve target was removed, use htmlview instead (see bpo-36329)" # Targets for daily automated doc build # By default, Sphinx only rebuilds pages where the page content has changed. diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst index 0ca7b003bf4..6a2d47891b4 100644 --- a/Doc/library/wsgiref.rst +++ b/Doc/library/wsgiref.rst @@ -813,30 +813,76 @@ Examples This is a working "Hello World" WSGI application:: + """ + Every WSGI application must have an application object - a callable + object that accepts two arguments. For that purpose, we're going to + use a function (note that you're not limited to a function, you can + use a class for example). The first argument passed to the function + is a dictionary containing CGI-style environment variables and the + second variable is the callable object. + """ from wsgiref.simple_server import make_server - # Every WSGI application must have an application object - a callable - # object that accepts two arguments. For that purpose, we're going to - # use a function (note that you're not limited to a function, you can - # use a class for example). The first argument passed to the function - # is a dictionary containing CGI-style environment variables and the - # second variable is the callable object. + def hello_world_app(environ, start_response): - status = '200 OK' # HTTP Status - headers = [('Content-type', 'text/plain; charset=utf-8')] # HTTP Headers + status = "200 OK" # HTTP Status + headers = [("Content-type", "text/plain; charset=utf-8")] # HTTP Headers start_response(status, headers) # The returned object is going to be printed return [b"Hello World"] - with make_server('', 8000, hello_world_app) as httpd: + with make_server("", 8000, hello_world_app) as httpd: print("Serving on port 8000...") # Serve until process is killed httpd.serve_forever() -Example of a WSGI application serving the current directory, accept optional -directory and port number (default: 8000) on the command line: -.. literalinclude:: ../../Tools/scripts/serve.py +Example of a WSGI application serving the current directory, accept optional +directory and port number (default: 8000) on the command line:: + + """ + Small wsgiref based web server. Takes a path to serve from and an + optional port number (defaults to 8000), then tries to serve files. + MIME types are guessed from the file names, 404 errors are raised + if the file is not found. + """ + import mimetypes + import os + import sys + from wsgiref import simple_server, util + + + def app(environ, respond): + # Get the file name and MIME type + fn = os.path.join(path, environ["PATH_INFO"][1:]) + if "." not in fn.split(os.path.sep)[-1]: + fn = os.path.join(fn, "index.html") + mime_type = mimetypes.guess_type(fn)[0] + + # Return 200 OK if file exists, otherwise 404 Not Found + if os.path.exists(fn): + respond("200 OK", [("Content-Type", mime_type)]) + return util.FileWrapper(open(fn, "rb")) + else: + respond("404 Not Found", [("Content-Type", "text/plain")]) + return [b"not found"] + + + if __name__ == "__main__": + # Get the path and port from command-line arguments + path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd() + port = int(sys.argv[2]) if len(sys.argv) > 2 else 8000 + + # Make and start the server until control-c + httpd = simple_server.make_server("", port, app) + print(f"Serving {path} on port {port}, control-C to stop") + try: + httpd.serve_forever() + except KeyboardInterrupt: + print("Shutting down.") + httpd.server_close() + + diff --git a/Doc/make.bat b/Doc/make.bat index f3e9b44d61d..d9a7aa4ca7f 100644 --- a/Doc/make.bat +++ b/Doc/make.bat @@ -111,7 +111,7 @@ echo. Provided by Sphinx: echo. html, htmlhelp, latex, text echo. suspicious, linkcheck, changes, doctest echo. Provided by this script: -echo. clean, check, serve, htmlview +echo. clean, check, htmlview echo. echo.All arguments past the first one are passed through to sphinx-build as echo.filenames to build or are ignored. See README.rst in this directory or @@ -184,7 +184,7 @@ cmd /S /C "%SPHINXLINT% -i tools" goto end :serve -cmd /S /C "%PYTHON% ..\Tools\scripts\serve.py "%BUILDDIR%\html"" +echo.The serve target was removed, use htmlview instead (see bpo-36329) goto end :end diff --git a/Misc/NEWS.d/next/Documentation/2022-04-06-11-53-41.bpo-36329.EVtAtK.rst b/Misc/NEWS.d/next/Documentation/2022-04-06-11-53-41.bpo-36329.EVtAtK.rst new file mode 100644 index 00000000000..67398de51ae --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2022-04-06-11-53-41.bpo-36329.EVtAtK.rst @@ -0,0 +1 @@ +Remove 'make -C Doc serve' in favour of 'make -C Doc htmlview' diff --git a/Tools/scripts/README b/Tools/scripts/README index ba0f662c45f..c1d66731ba6 100644 --- a/Tools/scripts/README +++ b/Tools/scripts/README @@ -57,7 +57,6 @@ reindent.py Change .py files to use 4-space indents reindent-rst.py Fix-up reStructuredText file whitespace rgrep.py Reverse grep through a file (useful for big logfiles) run_tests.py Run the test suite with more sensible default options -serve.py Small wsgiref-based web server, used in make serve in Doc stable_abi.py Stable ABI checks and file generators. suff.py Sort a list of files by suffix texi2html.py Convert GNU texinfo files into HTML diff --git a/Tools/scripts/serve.py b/Tools/scripts/serve.py deleted file mode 100755 index 7ac9c105078..00000000000 --- a/Tools/scripts/serve.py +++ /dev/null @@ -1,36 +0,0 @@ -#!/usr/bin/env python3 -''' -Small wsgiref based web server. Takes a path to serve from and an -optional port number (defaults to 8000), then tries to serve files. -Mime types are guessed from the file names, 404 errors are raised -if the file is not found. Used for the make serve target in Doc. -''' -import sys -import os -import mimetypes -from wsgiref import simple_server, util - -def app(environ, respond): - - fn = os.path.join(path, environ['PATH_INFO'][1:]) - if '.' not in fn.split(os.path.sep)[-1]: - fn = os.path.join(fn, 'index.html') - type = mimetypes.guess_type(fn)[0] - - if os.path.exists(fn): - respond('200 OK', [('Content-Type', type)]) - return util.FileWrapper(open(fn, "rb")) - else: - respond('404 Not Found', [('Content-Type', 'text/plain')]) - return [b'not found'] - -if __name__ == '__main__': - path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd() - port = int(sys.argv[2]) if len(sys.argv) > 2 else 8000 - httpd = simple_server.make_server('', port, app) - print("Serving {} on port {}, control-C to stop".format(path, port)) - try: - httpd.serve_forever() - except KeyboardInterrupt: - print("Shutting down.") - httpd.server_close()