From 9616c6f4571cc931d0999f0ae817764d85d8a5d7 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 6 Apr 2022 11:50:59 +0300 Subject: [PATCH 1/4] bpo-36329: Use real file:// path to open local file --- Doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/Makefile b/Doc/Makefile index 61a7ce0d0981f0..56ab58a4883a58 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -141,7 +141,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/* From 38747aec718640d88169f6ba6e45ba10a873818c Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 6 Apr 2022 11:56:00 +0300 Subject: [PATCH 2/4] bpo-36329: Remove 'make -C Doc serve' in favour of 'make -C Doc htmlview' --- Doc/Makefile | 7 +--- Doc/library/wsgiref.rst | 4 --- Doc/make.bat | 7 +--- .../2022-04-06-11-53-41.bpo-36329.EVtAtK.rst | 1 + Tools/scripts/README | 1 - Tools/scripts/serve.py | 36 ------------------- 6 files changed, 3 insertions(+), 53 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 56ab58a4883a58..a0c08ad488b2c9 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 @@ -23,7 +22,7 @@ ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) $(SPHINXERRORHANDLING) . build/$(BUILDER) $(SOURCES) .PHONY: help build html htmlhelp latex text texinfo changes linkcheck \ - suspicious coverage doctest pydoc-topics htmlview clean dist check serve \ + suspicious coverage doctest pydoc-topics htmlview clean dist check \ autobuild-dev autobuild-stable venv help: @@ -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 @@ -218,9 +216,6 @@ check: $(SPHINXLINT) -i tools -i $(VENVDIR) -i README.rst $(SPHINXLINT) ../Misc/NEWS.d/next/ -serve: - $(PYTHON) ../Tools/scripts/serve.py build/html $(SERVE_PORT) - # Targets for daily automated doc build # By default, Sphinx only rebuilds pages where the page content has changed. # This means it doesn't always pick up changes to preferred link targets, etc diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst index e924448b86d7f3..d9d556c22da31d 100644 --- a/Doc/library/wsgiref.rst +++ b/Doc/library/wsgiref.rst @@ -782,7 +782,3 @@ This is a working "Hello World" WSGI application:: 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 diff --git a/Doc/make.bat b/Doc/make.bat index f3e9b44d61d4a9..33b70c5b88bc1e 100644 --- a/Doc/make.bat +++ b/Doc/make.bat @@ -74,7 +74,6 @@ rem Targets that don't require sphinx-build if "%1" EQU "" goto help if "%1" EQU "help" goto help if "%1" EQU "check" goto check -if "%1" EQU "serve" goto serve if "%1" == "clean" ( rmdir /q /s "%BUILDDIR%" goto end @@ -111,7 +110,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 @@ -183,9 +182,5 @@ goto end cmd /S /C "%SPHINXLINT% -i tools" goto end -:serve -cmd /S /C "%PYTHON% ..\Tools\scripts\serve.py "%BUILDDIR%\html"" -goto end - :end popd 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 00000000000000..67398de51aed2e --- /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 ba0f662c45f0c5..c1d66731ba6495 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 7ac9c105078329..00000000000000 --- 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() From 5ed07588130ea6d156d0167ba430e7b3f62a95a2 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 8 Apr 2022 16:44:33 +0300 Subject: [PATCH 3/4] bpo-36329: Keep serve target but tell to use htmlview instead --- Doc/Makefile | 5 ++++- Doc/make.bat | 5 +++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/Doc/Makefile b/Doc/Makefile index a0c08ad488b2c9..3a3417bf99af3b 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -22,7 +22,7 @@ ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) $(SPHINXERRORHANDLING) . build/$(BUILDER) $(SOURCES) .PHONY: help build html htmlhelp latex text texinfo changes linkcheck \ - suspicious coverage doctest pydoc-topics htmlview clean dist check \ + suspicious coverage doctest pydoc-topics htmlview clean dist check serve \ autobuild-dev autobuild-stable venv help: @@ -216,6 +216,9 @@ check: $(SPHINXLINT) -i tools -i $(VENVDIR) -i README.rst $(SPHINXLINT) ../Misc/NEWS.d/next/ +serve: + @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. # This means it doesn't always pick up changes to preferred link targets, etc diff --git a/Doc/make.bat b/Doc/make.bat index 33b70c5b88bc1e..d9a7aa4ca7fa6c 100644 --- a/Doc/make.bat +++ b/Doc/make.bat @@ -74,6 +74,7 @@ rem Targets that don't require sphinx-build if "%1" EQU "" goto help if "%1" EQU "help" goto help if "%1" EQU "check" goto check +if "%1" EQU "serve" goto serve if "%1" == "clean" ( rmdir /q /s "%BUILDDIR%" goto end @@ -182,5 +183,9 @@ goto end cmd /S /C "%SPHINXLINT% -i tools" goto end +:serve +echo.The serve target was removed, use htmlview instead (see bpo-36329) +goto end + :end popd From d0e9f2e32e3580c37d5c028f6c3bad3cfde24a45 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 8 Apr 2022 19:33:50 +0300 Subject: [PATCH 4/4] bpo-36329: Retain code from serve.py as an example --- Doc/library/wsgiref.rst | 68 +++++++++++++++++++++++++++++++++++------ 1 file changed, 59 insertions(+), 9 deletions(-) diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst index d9d556c22da31d..182c5c4b7175cb 100644 --- a/Doc/library/wsgiref.rst +++ b/Doc/library/wsgiref.rst @@ -759,26 +759,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:: + + """ + 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() + +