diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 1f87153f59..8f392ba53c 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -132,6 +132,11 @@ jobs: LITESTAR_DOCS_IGNORE_MISSING_EXAMPLE_OUTPUT: 1 run: poetry run make docs + - name: Check docs links + env: + LITESTAR_DOCS_IGNORE_MISSING_EXAMPLE_OUTPUT: 1 + run: poetry run make docs-linkcheck + - name: Save PR number env: PR_NUMBER: ${{ github.event.number }} diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 9d40659bcc..38e9c09820 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -94,8 +94,8 @@ Project documentation The documentation is located in the ``/docs`` directory and is `ReST `_ and `Sphinx `_. If you're unfamiliar with any of those, -`ReStructuredText primer `_ and -`Sphinx quickstart `_ are recommended reads. +`ReStructuredText primer `_ and +`Sphinx quickstart `_ are recommended reads. Docs theme and appearance +++++++++++++++++++++++++ @@ -123,7 +123,7 @@ restructure the docs, etc., but make sure to follow these guidelines: - Opt for `Oxford commas `_ when listing a series of terms - Keep examples simple and self contained - Provide links where applicable -- Use `intersphinx `_ wherever possible when +- Use `intersphinx `_ wherever possible when referencing external libraries - Provide diagrams using `mermaidjs `_ where applicable and possible @@ -216,7 +216,7 @@ Creating a new release ---------------------- 1. Increment the version in ``pyproject.toml`` according to the - `versioning scheme `_ + `versioning scheme `_ 2. `Draft a new release `_ on GitHub * Use ``vMAJOR.MINOR.PATCH`` (e.g. ``v1.2.3``) as both the tag and release title diff --git a/Makefile b/Makefile index 8c440bd562..5ae02c1455 100644 --- a/Makefile +++ b/Makefile @@ -14,6 +14,14 @@ docs-serve: docs: docs-clean sphinx-build -M html docs docs/_build/ -a -j auto -W --keep-going +.PHONY: docs-linkcheck +docs-linkcheck: + sphinx-build -b linkcheck ./docs ./docs/_build -D linkcheck_ignore='http://.*','https://.*' + +.PHONY: docs-linkcheck-full +docs-linkcheck-full: + sphinx-build -b linkcheck ./docs ./docs/_build -D linkcheck_anchors=0 + .PHONY: test-examples test-examples: pytest tests/examples diff --git a/docs/conf.py b/docs/conf.py index c8a9f4c30b..4bf2055296 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -200,6 +200,12 @@ re.compile(r"litestar\.dto.*"): re.compile(".*T|.*FieldDefinition|Empty"), } +# Do not warn about broken links to the following: +linkcheck_ignore = [ + r"http://localhost(:\d+)?", + r"http://127.0.0.1(:\d+)?", + "http://testserver", +] auto_pytabs_min_version = (3, 8) auto_pytabs_max_version = (3, 11) @@ -268,9 +274,22 @@ def update_html_context( context["generate_toctree_html"] = partial(context["generate_toctree_html"], startdepth=0) -def setup(app: Sphinx) -> dict[str, bool]: - app.setup_extension("litestar_sphinx_theme") +def delayed_setup(app: Sphinx) -> None: + """ + When running linkcheck pydata_sphinx_theme causes a build failure, and checking + the builder in the initial `setup` function call is not possible, so the check + and extension setup has to be delayed until the builder is initialized. + """ + if app.builder.name == "linkcheck": + return + app.setup_extension("pydata_sphinx_theme") app.connect("html-page-context", update_html_context) + +def setup(app: Sphinx) -> dict[str, bool]: + app.connect("builder-inited", delayed_setup, priority=0) + + app.setup_extension("litestar_sphinx_theme") + return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/docs/migration/fastapi.rst b/docs/migration/fastapi.rst index 8eba6462da..a1d5127a4f 100644 --- a/docs/migration/fastapi.rst +++ b/docs/migration/fastapi.rst @@ -62,7 +62,9 @@ controller methods. The handler can then be registered on an application or rout .. seealso:: To learn more about registering routes, check out this chapter - in the documentation: :ref:`registering routes ` + in the documentation: + + * :ref:`Routing - Registering Routes ` Routers and Routes ~~~~~~~~~~~~~~~~~~ @@ -181,7 +183,9 @@ and to easily access dependencies from higher levels. .. seealso:: To learn more about dependency injection, check out this chapter - in the documentation: `Dependency injection `__ + in the documentation: + + * :doc:`/usage/dependency-injection` Authentication ^^^^^^^^^^^^^^ @@ -232,7 +236,9 @@ preferred way of handling this is extending :doc:`/usage/security/abstract-authe .. seealso:: To learn more about security and authentication, check out this chapter in the - documentation: `Security `_ + documentation: + + * :doc:`/usage/security/index` Dependency overrides ^^^^^^^^^^^^^^^^^^^^ @@ -260,5 +266,4 @@ Middleware Pure ASGI middleware is fully compatible, and can be used with any ASGI framework. Middlewares that make use of FastAPI/Starlette specific middleware features such as Starlette’s `BaseHTTPMiddleware `_ are not compatible, -but can be easily replaced by making use of `AbstractMiddleware -`_ +but can be easily replaced by :doc:`Creating Middlewares `. diff --git a/docs/migration/flask.rst b/docs/migration/flask.rst index b8afbf2a84..a043fc4001 100644 --- a/docs/migration/flask.rst +++ b/docs/migration/flask.rst @@ -128,7 +128,9 @@ Path parameters .. seealso:: To learn more about path parameters, check out this chapter - in the documentation: `Path parameters `_ + in the documentation: + + * :doc:`/usage/routing/parameters` Request object ~~~~~~~~~~~~~~ @@ -282,8 +284,9 @@ in Litestar. .. seealso:: - To learn more about static files, check out this chapter in the documentation: - `Static files `_ + To learn more about static files, check out this chapter in the documentation + + * :doc:`/usage/static-files` Templates ~~~~~~~~~ @@ -335,7 +338,8 @@ In addition to Jinja, Litestar supports `Mako `_ .. seealso:: To learn more about templates, check out this chapter in the documentation: - `Template engines `_ + + * :doc:`/usage/templating` Setting cookies and headers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -394,8 +398,8 @@ Setting cookies and headers To learn more about response headers and cookies, check out these chapters in the documentation: - - :ref:`Response headers ` - - :ref:`Response cookies ` + - :ref:`Responses - Setting Response Headers ` + - :ref:`Responses - Setting Response Cookies ` Redirects ~~~~~~~~~ @@ -488,7 +492,9 @@ Instead of using the ``abort`` function, raise an ``HTTPException``: .. seealso:: - To learn more about exceptions, check out this chapter in the documentation: `Exceptions `_ + To learn more about exceptions, check out this chapter in the documentation: + + * :doc:`/usage/exceptions` Setting status codes ~~~~~~~~~~~~~~~~~~~~ @@ -636,4 +642,5 @@ Error handling .. seealso:: To learn more about exception handling, check out this chapter in the documentation: - :ref:`usage/exceptions:exception handling` + + * :ref:`usage/exceptions:exception handling` diff --git a/docs/release-notes/changelog.rst b/docs/release-notes/changelog.rst index 7a8d90b9b5..b042696157 100644 --- a/docs/release-notes/changelog.rst +++ b/docs/release-notes/changelog.rst @@ -613,7 +613,7 @@ .. change:: Expose ``ParsedType`` as public API :type: feature - :pr: 1677, 1567 + :pr: 1677 1567 Expose the previously private :class:`litestar.typing.ParsedType`. This is mainly indented for usage with @@ -747,7 +747,7 @@ .. change:: DTOs: Hybrid properties and association proxies in ``SQLAlchemyDTO`` :type: feature - :pr: 1754, 1776 + :pr: 1754 1776 The ``~litestar.contrib.sqlalchemy.dto.SQLAlchemyDTO`` now supports `hybrid attribute `_ @@ -919,7 +919,7 @@ .. change:: Incorrect ``sync_to_thread`` usage warnings for generator dependencies :type: bugfix - :pr: 1716, 1740 + :pr: 1716 1740 :issue: 1711 A bug was fixed that caused incorrect warnings about missing ``sync_to_thread`` @@ -1112,7 +1112,7 @@ .. change:: Warn about sync callables in route handlers and dependencies without an explicit ``sync_to_thread`` value :type: feature - :pr: 1648, 1655 + :pr: 1648 1655 A warning will now be raised when a synchronous callable is being used in an :class:`~.handlers.HTTPRouteHandler` or :class:`~.di.Provide`, without setting @@ -2000,7 +2000,7 @@ .. change:: Fix ``JSON.parse`` error in ReDoc and Swagger OpenAPI handlers :type: bugfix - :pr: 1363ad + :pr: 1363 The HTML generated by the ReDoc and Swagger OpenAPI handlers would cause `JSON.parse `_ @@ -2037,7 +2037,7 @@ .. change:: Move 3rd party integration plugins to ``contrib`` :type: misc :breaking: - :pr: Move 3rd party integration plugins to ``contrib`` + :pr: 1279 1252 - Move ``plugins.piccolo_orm`` > ``contrib.piccolo_orm`` - Move ``plugins.tortoise_orm`` > ``contrib.tortoise_orm`` @@ -2362,13 +2362,13 @@ cookie. - .. change:: Fix https://github.com/litestar-org/starlite/issues/1201: Can not serve static file in ``/`` path + .. change:: Fix https://github.com/litestar-org/litestar/issues/1201: Can not serve static file in ``/`` path :type: bugfix :issue: 1201 A validation error made it impossible to serve static files from the root path ``/`` . - .. change:: Fix https://github.com/litestar-org/starlite/issues/1149: Middleware not excluding static path + .. change:: Fix https://github.com/litestar-org/litestar/issues/1149: Middleware not excluding static path :type: bugfix :issue: 1149 diff --git a/docs/tutorials/sqlalchemy/4-final-touches-and-recap.rst b/docs/tutorials/sqlalchemy/4-final-touches-and-recap.rst index 5720af4c5f..e22d1e541f 100644 --- a/docs/tutorials/sqlalchemy/4-final-touches-and-recap.rst +++ b/docs/tutorials/sqlalchemy/4-final-touches-and-recap.rst @@ -63,4 +63,4 @@ engine and session lifecycle, and register our ``transaction`` dependency. .. seealso:: - :doc:`SQLAlchemy Plugins Usage Guide ` + * :doc:`SQLAlchemy Plugins Usage Guide ` diff --git a/docs/tutorials/todo-app/0-application-basics.rst b/docs/tutorials/todo-app/0-application-basics.rst index 93bdd678ff..73b735f860 100644 --- a/docs/tutorials/todo-app/0-application-basics.rst +++ b/docs/tutorials/todo-app/0-application-basics.rst @@ -87,7 +87,8 @@ Litestar that you only want to use this function when a ``GET`` request is being .. seealso:: - :doc:`/usage/routing/handlers` + + * :doc:`/usage/routing/handlers` Type annotations @@ -134,7 +135,8 @@ as the first argument: .. seealso:: - :doc:`/usage/applications` + + * :doc:`/usage/applications` @@ -163,4 +165,5 @@ When you run ``litestar run``, it will recognise the ``app.py`` file and the .. seealso:: - :doc:`/usage/cli` + + * :doc:`/usage/cli` diff --git a/docs/tutorials/todo-app/1-accessing-the-list.rst b/docs/tutorials/todo-app/1-accessing-the-list.rst index 1f01f273a4..5be553d96c 100644 --- a/docs/tutorials/todo-app/1-accessing-the-list.rst +++ b/docs/tutorials/todo-app/1-accessing-the-list.rst @@ -206,7 +206,8 @@ be compared against the ``TodoItem.done`` attribute: .. seealso:: - :ref:`usage/routing/parameters:type coercion` + + * :ref:`Routing - Parameters - Type coercion ` Making the query parameter optional @@ -244,7 +245,8 @@ supplied. .. seealso:: - :ref:`usage/routing/parameters:query parameters` + + * :ref:`Routing - Parameters - Query Parameters ` Interactive documentation diff --git a/docs/tutorials/todo-app/2-interacting-with-the-list.rst b/docs/tutorials/todo-app/2-interacting-with-the-list.rst index a3382982de..98d3cf85b7 100644 --- a/docs/tutorials/todo-app/2-interacting-with-the-list.rst +++ b/docs/tutorials/todo-app/2-interacting-with-the-list.rst @@ -24,7 +24,8 @@ request data in the form of JSON and use the type annotation we gave it to conve into the correct format. .. seealso:: - :doc:`/usage/requests` + + * :doc:`/usage/requests` Using the interactive documentation to test a route @@ -122,4 +123,5 @@ list. .. seealso:: - :ref:`usage/routing/parameters:path parameters` + + * :ref:`usage/routing/parameters:path parameters` diff --git a/docs/usage/applications.rst b/docs/usage/applications.rst index f7ad3e5cb4..3bd7aeec21 100644 --- a/docs/usage/applications.rst +++ b/docs/usage/applications.rst @@ -22,7 +22,8 @@ and Route Handlers should be registered on it. .. seealso:: To learn more about registering routes, check out this chapter in the documentation: - :ref:`usage/routing/overview:Registering Routes` + + * :ref:`Routing - Registering Routes ` Startup and Shutdown diff --git a/docs/usage/channels.rst b/docs/usage/channels.rst index a9e2c24b4a..cbf0ef2721 100644 --- a/docs/usage/channels.rst +++ b/docs/usage/channels.rst @@ -255,7 +255,8 @@ be used to fetch this history and put it into a subscriber's :term:`event stream previous events have been processed. .. seealso:: - `Managing backpressure` + + * `Managing backpressure`_ The ``Subscriber`` diff --git a/docs/usage/cli.rst b/docs/usage/cli.rst index fef1872d47..8fcfe81803 100644 --- a/docs/usage/cli.rst +++ b/docs/usage/cli.rst @@ -58,8 +58,8 @@ litestar The main entrypoint to the Litestar CLI is the ``litestar`` command. -If you don't pass the ``--app`` flag, the application will be automatically discovered, as explained in the -`autodiscovery section `_. +If you don't pass the ``--app`` flag, the application will be automatically discovered, as explained in +`Autodiscovery`_. Options ~~~~~~~ diff --git a/docs/usage/databases/sqlalchemy/models_and_repository.rst b/docs/usage/databases/sqlalchemy/models_and_repository.rst index b6f4521809..0a3e237115 100644 --- a/docs/usage/databases/sqlalchemy/models_and_repository.rst +++ b/docs/usage/databases/sqlalchemy/models_and_repository.rst @@ -75,4 +75,5 @@ Alternately, you may use the ``SQLAlchemySyncRepository`` class for your synchro :language: python .. seealso:: - :doc:`/tutorials/repository-tutorial/index` + + * :doc:`/tutorials/repository-tutorial/index` diff --git a/docs/usage/middleware/builtin-middleware.rst b/docs/usage/middleware/builtin-middleware.rst index 859a4609e2..3a903ccf39 100644 --- a/docs/usage/middleware/builtin-middleware.rst +++ b/docs/usage/middleware/builtin-middleware.rst @@ -281,7 +281,7 @@ which offers strong AES-CGM encryption security best practices while support coo .. seealso:: - :class:`CookieBackendConfig ` + * :class:`CookieBackendConfig ` Server-side sessions @@ -296,5 +296,5 @@ and load the appropriate data from the store .. seealso:: - - :doc:`/usage/stores` - - :class:`ServerSideSessionConfig ` + * :doc:`/usage/stores` + * :class:`ServerSideSessionConfig ` diff --git a/docs/usage/middleware/index.rst b/docs/usage/middleware/index.rst index 7913ff5db1..e2463c08f2 100644 --- a/docs/usage/middleware/index.rst +++ b/docs/usage/middleware/index.rst @@ -9,8 +9,9 @@ See :doc:`the documentation regarding these ` in the migration guide. + If you're coming from Starlette / FastAPI, take a look at the migration guide: + + * :ref:`Migration - FastAPI/Starlette - Middlewares ` .. toctree:: diff --git a/docs/usage/openapi.rst b/docs/usage/openapi.rst index e2dd089e6c..c3bc2dcc21 100644 --- a/docs/usage/openapi.rst +++ b/docs/usage/openapi.rst @@ -304,7 +304,7 @@ Customizing Pydantic model schemas ---------------------------------- You can customize the OpenAPI schemas generated for pydantic models by following the guidelines in -the `pydantic docs `_. +the `Pydantic docs `_. Additionally, you can affect how pydantic models are translated into OpenAPI ``components`` by settings a special dunder attribute on the model called ``__schema_name__``: diff --git a/docs/usage/plugins.rst b/docs/usage/plugins.rst index 51400402f2..8c4b64ce0a 100644 --- a/docs/usage/plugins.rst +++ b/docs/usage/plugins.rst @@ -5,7 +5,7 @@ Litestar supports a plugin system that allows you to extend the functionality of .. seealso:: - :doc:`/usage/databases/sqlalchemy/plugins/index` + * :doc:`/usage/databases/sqlalchemy/plugins/index` Plugins are defined by protocols, and any type that satisfies a protocol can be included in the ``plugins`` argument of the :class:`app `. diff --git a/docs/usage/responses.rst b/docs/usage/responses.rst index 9e57d48401..d8199e66bc 100644 --- a/docs/usage/responses.rst +++ b/docs/usage/responses.rst @@ -517,7 +517,7 @@ Of the two declarations of ``my-cookie`` only the route handler one will be used .. seealso:: - :class:`Cookie reference <.datastructures.cookie.Cookie>` + * :class:`Cookie reference <.datastructures.cookie.Cookie>` diff --git a/docs/usage/routing/handlers.rst b/docs/usage/routing/handlers.rst index c26cc381e9..3f43e1bc58 100644 --- a/docs/usage/routing/handlers.rst +++ b/docs/usage/routing/handlers.rst @@ -312,8 +312,8 @@ These requirements are enforced using inspection, and if any of them is unfulfil .. seealso:: - :class:`WebsocketRouteHandler ` - :doc:`/usage/websockets` + * :class:`WebsocketRouteHandler ` + * :doc:`/usage/websockets` ASGI route handlers diff --git a/docs/usage/routing/overview.rst b/docs/usage/routing/overview.rst index 71764c3954..78ad8dc6a7 100644 --- a/docs/usage/routing/overview.rst +++ b/docs/usage/routing/overview.rst @@ -174,7 +174,7 @@ better code organization and organize code by logical concerns. ... The above is a simple example of a "CRUD" controller for a model called ``UserOrder``. You can place as -many `route handler methods `_ on a controller, +many :doc:`route handler methods ` on a controller, as long as the combination of path+http method is unique. The ``path`` that is defined on the Controller is appended before the path that is defined for the route handlers declared diff --git a/docs/usage/static-files.rst b/docs/usage/static-files.rst index 9c3eaedb7a..fb1b8f2d47 100644 --- a/docs/usage/static-files.rst +++ b/docs/usage/static-files.rst @@ -32,7 +32,7 @@ no file is found the application will look for a ``404.html`` file in order to r You can provide a ``name`` parameter to ``StaticFilesConfig`` to identify the given config and generate links to files in folders belonging to that config. ``name`` should be a unique string across all static configs and -`route handlers `_. +:doc:`/usage/routing/handlers`. .. code-block:: python diff --git a/docs/usage/stores.rst b/docs/usage/stores.rst index 7b6c30fa42..d9059b8d8a 100644 --- a/docs/usage/stores.rst +++ b/docs/usage/stores.rst @@ -185,7 +185,7 @@ It operates on a few basic principles: - An initial mapping of stores can be provided to the registry - Registered stores can be requested with :meth:`get <.registry.StoreRegistry.get>` - If a store has been requested that has not been registered yet, a store of that name will be created and registered - using the `default factory `_ + using the `the default factory`_ .. literalinclude:: /examples/stores/registry.py diff --git a/docs/usage/templating.rst b/docs/usage/templating.rst index 868f5110dc..77e978dcae 100644 --- a/docs/usage/templating.rst +++ b/docs/usage/templating.rst @@ -382,7 +382,5 @@ the call method. For example: Run the example with ``uvicorn template_functions:app`` , visit http://127.0.0.1:8000, and you'll see - .. image:: /images/examples/template_engine_callable.png - :target: /images/examples/template_engine_callable.png - :alt: Template engine callable example + :alt: Template engine callable example diff --git a/litestar/openapi/spec/license.py b/litestar/openapi/spec/license.py index 0911a888d1..b779bb44a8 100644 --- a/litestar/openapi/spec/license.py +++ b/litestar/openapi/spec/license.py @@ -16,7 +16,7 @@ class License(BaseSchemaObject): identifier: str | None = None """An - `SPDX `_ license expression for the API. + `SPDX `_ license expression for the API. The ``identifier`` field is mutually exclusive of the ``url`` field. """