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

Author: hugovk

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.

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:
+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()
+
 
-.. literalinclude:: ../../Tools/scripts/serve.py

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

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'

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