From b68a142a356ede730083347f254e1eae8b5c803e Mon Sep 17 00:00:00 2001 From: Marcelo Trylesinski Date: Sat, 30 Nov 2024 12:41:25 +0100 Subject: [PATCH] Replace `mkautodoc` by `mkdocstrings` (#2776) --- docs/applications.md | 12 ++++++--- mkdocs.yml | 25 +++++++++++++++++- requirements.txt | 3 ++- starlette/applications.py | 55 +++++++++++++++++++-------------------- 4 files changed, 61 insertions(+), 34 deletions(-) diff --git a/docs/applications.md b/docs/applications.md index a3be21f7..695f3801 100644 --- 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 83d245e0..55bf1c22 100644 --- 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 1dc7bc7c..edec1987 100644 --- 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 aae38f58..0a717bb3 100644 --- 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 (