Merge pull request #2676 from gresm/docs-serve

Serving documentation with a simple server.

buildconfig/stubs/pygame/docs/__init__.pyi

@@ -0,0 +1,6 @@
+from pathlib import Path
+
+PKG_DIR: Path
+
+
+def has_local_docs() -> bool: ...

buildconfig/stubs/pygame/docs/__main__.pyi

@@ -0,0 +1 @@
+def main(): ...

buildconfig/stubs/pygame/docs/serve.pyi

@@ -0,0 +1,13 @@
+from http.server import SimpleHTTPRequestHandler
+
+
+class DocsHandler(SimpleHTTPRequestHandler): ...
+
+
+def serve(address: str, port: str): ...
+
+
+def main(): ...
+
+
+TARGET: str

buildconfig/stubs/pygame/docs/static.pyi

@@ -0,0 +1,4 @@
+def open_docs(): ...
+
+
+def main(): ...

docs/__init__.py

@@ -0,0 +1,11 @@
+# python -m pygame.docs
+
+from pathlib import Path
+
+
+PKG_DIR = Path(__file__).absolute().parent / "generated"
+
+
+# for test suite to confirm pygame-ce built with local docs
+def has_local_docs():
+    return PKG_DIR.exists()

docs/__main__.py

@@ -1,37 +1,15 @@
-# python -m pygame.docs
+import platform
 
-import os
-import webbrowser
-from urllib.parse import quote, urlunparse
+from pygame.docs.serve import main as serve
+from pygame.docs.static import main as static
 
 
-def _iterpath(path):
-    path, last = os.path.split(path)
-    if last:
-        yield from _iterpath(path)
-        yield last
-
-
-# for test suite to confirm pygame-ce built with local docs
-def has_local_docs():
-    pkg_dir = os.path.dirname(os.path.abspath(__file__))
-    main_page = os.path.join(pkg_dir, "generated", "index.html")
-    return os.path.exists(main_page)
-
-
-def open_docs():
-    pkg_dir = os.path.dirname(os.path.abspath(__file__))
-    main_page = os.path.join(pkg_dir, "generated", "index.html")
-    if os.path.exists(main_page):
-        url_path = quote("/".join(_iterpath(main_page)))
-        drive, rest = os.path.splitdrive(__file__)
-        if drive:
-            url_path = f"{drive}/{url_path}"
-        url = urlunparse(("file", "", url_path, "", "", ""))
+def main():
+    if platform.system() == "Linux":
+        serve()
     else:
-        url = "https://pyga.me/docs/"
-    webbrowser.open(url)
+        static()
 
 
 if __name__ == "__main__":
-    open_docs()
+    main()

docs/serve.py

@@ -0,0 +1,68 @@
+# python -m pygame.docs.serve
+
+import sys
+import webbrowser
+from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler
+
+from pygame.docs import PKG_DIR, has_local_docs
+
+
+class DocsHandler(SimpleHTTPRequestHandler):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs, directory=str(PKG_DIR))
+
+
+def serve(address: str, port: int):
+    with ThreadingHTTPServer((address, port), DocsHandler) as httpd:
+        try:
+            httpd.serve_forever()
+        except KeyboardInterrupt:
+            print("\nKeyboard interrupt received, exiting.")
+            sys.exit(0)
+
+
+TARGET = "localhost"
+
+
+def main():
+    print("Running a simple server to serve documentation.")
+    print(
+        "If you want to just open documentation files in the browser, "
+        "run 'python -m pygame.docs.static'."
+    )
+    if not has_local_docs():
+        print("ERROR: no local documentation found, cannot serve anything, exiting...")
+        sys.exit(1)
+    print("WARNING: this is not for production use!")
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "port",
+        action="store",
+        default=8000,
+        type=int,
+        nargs="?",
+        help="specify alternate port (default: 8000)",
+    )
+    parser.add_argument(
+        "--no-browser",
+        "-n",
+        action="store_false",
+        default=True,
+        dest="open_browser",
+        help="whether to open a browser tab",
+    )
+
+    parsed_args = parser.parse_args()
+
+    print(f"Serving on: http://{TARGET}:{parsed_args.port}")
+
+    if parsed_args.open_browser:
+        webbrowser.open(f"http://{TARGET}:{parsed_args.port}")
+
+    serve(TARGET, parsed_args.port)
+
+
+if __name__ == "__main__":
+    main()

docs/static.py

@@ -0,0 +1,24 @@
+import webbrowser
+
+from pygame.docs import PKG_DIR
+
+
+def open_docs():
+    main_page = PKG_DIR / "index.html"
+    if main_page.exists():
+        url = main_page.as_uri()
+    else:
+        url = "https://pyga.me/docs/"
+    webbrowser.open(url)
+
+
+def main():
+    print("Opening local documentation files in the browser.")
+    print(
+        "If you want to run a simple server instead, run 'python -m pygame.docs.serve'."
+    )
+    open_docs()
+
+
+if __name__ == "__main__":
+    main()

setup.py

@@ -839,13 +839,13 @@ def filter_files(path_obj, all_files, allowed_files, disallowed_files):
 
 
         # Other files have too many issues for now. setup.py, buildconfig, etc
-        python_directories = ["src_py", "test", "examples"]
+        python_directories = ["src_py", "test", "examples", "docs", "--exclude", "docs/reST"]
         if self.lint:
             commands = {
                 "clang-format": ["--dry-run", "--Werror", "-i"] + c_files,
                 "black": ["--check", "--diff"] + python_directories,
                 # Test directory has too much pylint warning for now
-                "pylint": ["src_py"],
+                "pylint": ["src_py", "docs"],
             }
         else:
             commands = {

test/docs_test.py

@@ -6,11 +6,11 @@
 
 class DocsIncludedTest(unittest.TestCase):
     def test_doc_import_works(self):
-        from pygame.docs.__main__ import has_local_docs, open_docs
+        from pygame.docs import has_local_docs, PKG_DIR
 
     @unittest.skipIf("CI" not in os.environ, "Docs not required for local builds")
     def test_docs_included(self):
-        from pygame.docs.__main__ import has_local_docs
+        from pygame.docs import has_local_docs
 
         self.assertTrue(has_local_docs())