From 4c4fcd1fc58ccbaa39b6b9f6d689b2b65aaff39e Mon Sep 17 00:00:00 2001
From: Vito Gamberini <vito@gamberini.email>
Date: Sun, 3 Nov 2024 20:14:59 -0500
Subject: [PATCH] docs: Improve docs

---
 docs/api.rst      |  5 ++-
 docs/conf.py      | 16 ++++++++
 src/nanoroute.pyi | 99 ++++++++++++++++++++++++++++++++++++++++++++---
 3 files changed, 113 insertions(+), 7 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 37a8465..dcefb98 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -1,4 +1,7 @@
 API Reference
 =============
 
-This is the API Reference
+.. automodule:: nanoroute
+  :members:
+
+  nanoroute
diff --git a/docs/conf.py b/docs/conf.py
index d1d7824..14f0475 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -13,3 +13,19 @@
     'fixed_sidebar': True,
     'github_banner': True,
 }
+
+autodoc_typehints = 'description'
+
+extensions = [
+    'sphinx.ext.autodoc'
+]
+
+import importlib.machinery
+import pathlib
+import sys
+
+sys.modules[project] = type(sys)(project)
+importlib.machinery.SourceFileLoader(
+    project,
+    f'{(pathlib.Path(__file__).parent.parent / 'src' /
+         'nanoroute.pyi').resolve()}').exec_module(sys.modules[project])
diff --git a/src/nanoroute.pyi b/src/nanoroute.pyi
index 178caab..b9b3630 100644
--- a/src/nanoroute.pyi
+++ b/src/nanoroute.pyi
@@ -4,30 +4,117 @@ T = TypeVar('handle')
 
 
 class router:
+  """Core class which represents a collection of HTTP verbs, routes, and
+  associated Python object handles.
+  """
   def __init__() -> None:
     ...
 
-  def get(route: str, /) -> Callable[[T], T]:
+  def route(self, methods: str | Iterable[str], route: str,
+            /) -> Callable[[T], T]:
+    """Base routing decorator
+
+    :param methods: Either a string or iterable of strings representing the
+        HTTP verbs to associate the route with
+    :param route: The route definition
+
+    :return: A registration decorator method
+
+    Usage::
+
+      import nanoroute
+      app = nanoroute.router()
+
+      @app.route('GET', '/about')
+      def handle_about():
+        ...
+    """
     ...
 
-  def post(route: str, /) -> Callable[[T], T]:
+  def get(self, route: str, /) -> Callable[[T], T]:
+    """
+    Convenience routing decorator, equivalent to ``route('GET', ...)``
+
+    :param route: The route definition
+
+    :return: A registration decorator method
+    """
     ...
 
-  def put(route: str, /) -> Callable[[T], T]:
+  def post(self, route: str, /) -> Callable[[T], T]:
+    """
+    Convenience routing decorator, equivalent to ``route('POST', ...)``
+
+    :param route: The route definition
+
+    :return: A registration decorator method
+    """
     ...
 
-  def delete(route: str, /) -> Callable[[T], T]:
+  def put(self, route: str, /) -> Callable[[T], T]:
+    """
+    Convenience routing decorator, equivalent to ``route('PUT', ...)``
+
+    :param route: The route definition
+
+    :return: A registration decorator method
+    """
     ...
 
-  def route(route: str | Iterable[str], /) -> Callable[[T], T]:
+  def delete(self, route: str, /) -> Callable[[T], T]:
+    """
+    Convenience routing decorator, equivalent to ``route('DELETE', ...)``
+
+    :param route: The route definition
+
+    :return: A registration decorator method
+    """
     ...
 
-  def lookup(method: str, path: str, /) -> tuple[Any, dict[str, str]]:
+  def lookup(self, method: str, path: str, /) -> tuple[Any, dict[str, str]]:
+    """
+    Base lookup function, finds a handle object given a method and a request
+    path
+
+    :param method: The HTTP verb from the associated request
+    :param path: The URL path from the associated request
+
+    :raises LookupError: If no matching handler is found
+
+    :return: The associated handle object and a ``{key: value}`` dictionary of
+        captured parameters
+
+    Usage::
+
+      handler, params = app.lookup('GET', '/about')
+    """
     ...
 
   def wsgi_app(
+      self,
       environ: dict[str, str],
       start_response: Callable[[str, dict[str, str]], Callable[[str], None]],
       /,
   ) -> bytes | Iterable[bytes]:
+    """
+    Convenience lookup function for compatibility with PEP 3333 WSGI servers,
+    stores the captured parameter dict in the ``nanoroute.params`` environ key.
+
+    :param environ: WSGI ``environ`` dict
+    :param start_response: WSGI ``start_response()`` method
+
+    :return: WSGI-compatible iterable
+
+    Equivalent to the following::
+
+      def wsgi_app(environ, start_response):
+        handler, params = app.lookup(
+            environ['REQUEST_METHOD'], 
+            environ['PATH_INFO']
+        )
+        environ['nanoroute.params'] = params
+        return handler(environ, start_response)
+
+      app.wsgi_app = wsgi_app
+    """
     ...