Replace `mkautodoc` by `mkdocstrings` (#2776)

diff --git a/docs/applications.md b/docs/applications.md
index a3be21f7f5c546f172767f457dba67aa2bf69a70..695f3801198ae49b414c8585e5ae5b6603c63fdf 100644 (file)
--- a/docs/applications.md
+++ b/docs/applications.md
@@ -45,10 +45,14 @@ routes = [
 app = Starlette(debug=True, routes=routes, lifespan=lifespan)
 ```
 
-### Instantiating the application
-
-::: starlette.applications.Starlette
-    :docstring:
+??? abstract "API Reference"
+    ::: starlette.applications.Starlette
+        options:
+            parameter_headings: false
+            show_root_heading: true
+            heading_level: 3
+            filters:
+                - "__init__"
 
 ### Storing state on the app instance
 

diff --git a/mkdocs.yml b/mkdocs.yml
index 83d245e040006ba14e8357e250d361870eee04cb..55bf1c22462db3f4d4978db6914d9542e823b384 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -55,9 +55,32 @@ nav:
       - Contributing: "contributing.md"
 
 markdown_extensions:
-  - mkautodoc
   - admonition
   - pymdownx.highlight
   - pymdownx.superfences
+  - pymdownx.details
   - pymdownx.tabbed:
       alternate_style: true
+
+watch:
+  - starlette
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_section_style: list
+            show_root_toc_entry: false
+            members_order: source
+            separate_signature: true
+            filters: ["!^_"]
+            docstring_options:
+              ignore_init_summary: true
+            merge_init_into_class: true
+            parameter_headings: true
+            show_signature_annotations: true
+            signature_crossrefs: true
+          import:
+            - url: https://docs.python.org/3/objects.inv

diff --git a/requirements.txt b/requirements.txt
index 1dc7bc7c7e5b893d2f15a84e74a113a333446c85..edec1987b1c3bd2bacadd0414fdd8c89623f8d1e 100644 (file)
--- a/requirements.txt
+++ b/requirements.txt
@@ -16,7 +16,8 @@ trio==0.27.0
 # Documentation
 mkdocs==1.6.1
 mkdocs-material==9.5.43
-mkautodoc==0.2.0
+mkdocstrings-python<1.12.0; python_version < "3.9"
+mkdocstrings-python==1.12.2; python_version >= "3.9"
 
 # Packaging
 build==1.2.2.post1

diff --git a/starlette/applications.py b/starlette/applications.py
index aae38f588daee19ce5bc60db044ef388be2fb570..0a717bb3af031f8b448f7b37df84e661236d89bd 100644 (file)
--- a/starlette/applications.py
+++ b/starlette/applications.py
@@ -25,34 +25,7 @@ P = ParamSpec("P")
 
 
 class Starlette:
-    """
-    Creates an application instance.
-
-    **Parameters:**
-
-    * **debug** - Boolean indicating if debug tracebacks should be returned on errors.
-    * **routes** - A list of routes to serve incoming HTTP and WebSocket requests.
-    * **middleware** - A list of middleware to run for every request. A starlette
-    application will always automatically include two middleware classes.
-    `ServerErrorMiddleware` is added as the very outermost middleware, to handle
-    any uncaught errors occurring anywhere in the entire stack.
-    `ExceptionMiddleware` is added as the very innermost middleware, to deal
-    with handled exception cases occurring in the routing or endpoints.
-    * **exception_handlers** - A mapping of either integer status codes,
-    or exception class types onto callables which handle the exceptions.
-    Exception handler callables should be of the form
-    `handler(request, exc) -> response` and may be either standard functions, or
-    async functions.
-    * **on_startup** - A list of callables to run on application startup.
-    Startup handler callables do not take any arguments, and may be either
-    standard functions, or async functions.
-    * **on_shutdown** - A list of callables to run on application shutdown.
-    Shutdown handler callables do not take any arguments, and may be either
-    standard functions, or async functions.
-    * **lifespan** - A lifespan context function, which can be used to perform
-    startup and shutdown tasks. This is a newer style that replaces the
-    `on_startup` and `on_shutdown` handlers. Use one or the other, not both.
-    """
+    """Creates an Starlette application."""
 
     def __init__(
         self: AppType,
@@ -64,6 +37,32 @@ class Starlette:
         on_shutdown: typing.Sequence[typing.Callable[[], typing.Any]] | None = None,
         lifespan: Lifespan[AppType] | None = None,
     ) -> None:
+        """Initializes the application.
+
+        Parameters:
+            debug: Boolean indicating if debug tracebacks should be returned on errors.
+            routes: A list of routes to serve incoming HTTP and WebSocket requests.
+            middleware: A list of middleware to run for every request. A starlette
+                application will always automatically include two middleware classes.
+                `ServerErrorMiddleware` is added as the very outermost middleware, to handle
+                any uncaught errors occurring anywhere in the entire stack.
+                `ExceptionMiddleware` is added as the very innermost middleware, to deal
+                with handled exception cases occurring in the routing or endpoints.
+            exception_handlers: A mapping of either integer status codes,
+                or exception class types onto callables which handle the exceptions.
+                Exception handler callables should be of the form
+                `handler(request, exc) -> response` and may be either standard functions, or
+                async functions.
+            on_startup: A list of callables to run on application startup.
+                Startup handler callables do not take any arguments, and may be either
+                standard functions, or async functions.
+            on_shutdown: A list of callables to run on application shutdown.
+                Shutdown handler callables do not take any arguments, and may be either
+                standard functions, or async functions.
+            lifespan: A lifespan context function, which can be used to perform
+                startup and shutdown tasks. This is a newer style that replaces the
+                `on_startup` and `on_shutdown` handlers. Use one or the other, not both.
+        """
         # The lifespan context function is a newer style that replaces
         # on_startup / on_shutdown handlers. Use one or the other, not both.
         assert lifespan is None or (