chore: Docs/update links

.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 }}

CONTRIBUTING.rst

@@ -94,8 +94,8 @@ Project documentation
 
 The documentation is located in the ``/docs`` directory and is `ReST <https://docutils.sourceforge.io/rst.html>`_ and
 `Sphinx <https://www.sphinx-doc.org/en/master/>`_. If you're unfamiliar with any of those,
-`ReStructuredText primer <https://www.sphinx-doc.org/en/master/lib/usage/restructuredtext/basics.html>`_ and
-`Sphinx quickstart <https://www.sphinx-doc.org/en/master/lib/usage/quickstart.html>`_ are recommended reads.
+`ReStructuredText primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ and
+`Sphinx quickstart <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_ 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 <https://en.wikipedia.org/wiki/Serial_comma>`_ when listing a series of terms
 - Keep examples simple and self contained
 - Provide links where applicable
-- Use `intersphinx <https://www.sphinx-doc.org/en/master/lib/usage/extensions/intersphinx.html>`_ wherever possible when
+- Use `intersphinx <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_ wherever possible when
  referencing external libraries
 - Provide diagrams using `mermaidjs <https://mermaid.js.org/>`_ where applicable and possible
 
@@ -216,7 +216,7 @@ Creating a new release
 ----------------------
 
 1. Increment the version in ``pyproject.toml`` according to the
- `versioning scheme <https://litestar-org.github.io/litestar/latest/litestar-releases.html#version-numbering>`_
+ `versioning scheme <https://litestar.dev/about/litestar-releases#version-numbering>`_
 2. `Draft a new release <https:/litestar-org/litestar/releases/new>`_ on GitHub
 
  * Use ``vMAJOR.MINOR.PATCH`` (e.g. ``v1.2.3``) as both the tag and release title

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

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}

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 <usage/routing/overview:registering routes>`
+ in the documentation:
+
+ * :ref:`Routing - Registering Routes <usage/routing/overview: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 <usage/6-dependency-injection/0-dependency-injection-intro/>`__
+ 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 <usage/8-security/0-intro/>`_
+ 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 <https://www.starlette.io/middleware/#basehttpmiddleware>`_ are not compatible,
-but can be easily replaced by making use of `AbstractMiddleware
-<usage/7-middleware/2-creating-middleware/2-using-abstract-middleware/>`_
+but can be easily replaced by :doc:`Creating Middlewares </usage/middleware/creating-middleware>`.

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 <usage/3-parameters/0-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 <usage/0-the-litestar-app/3-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 <https://www.makotemplates.org/>`_
 
 .. seealso::
  To learn more about templates, check out this chapter in the documentation:
- `Template engines <usage/16-templating/0-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 <usage/responses:setting response headers>`
- - :ref:`Response cookies <usage/responses:setting response cookies>`
+ - :ref:`Responses - Setting Response Headers <usage/responses:setting response headers>`
+ - :ref:`Responses - Setting Response Cookies <usage/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 <usage/17-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`

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 <https://docs.sqlalchemy.org/en/20/orm/extensions/hybrid.html>`_
@@ -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 <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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:/litestar-org/starlite/issues/1201: Can not serve static file in ``/`` path
+ .. change:: Fix https:/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:/litestar-org/starlite/issues/1149: Middleware not excluding static path
+ .. change:: Fix https:/litestar-org/litestar/issues/1149: Middleware not excluding static path
  :type: bugfix
  :issue: 1149
 

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 </usage/databases/sqlalchemy/plugins/index>`
+ * :doc:`SQLAlchemy Plugins Usage Guide </usage/databases/sqlalchemy/plugins/index>`

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`

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 <usage/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 <usage/routing/parameters:query parameters>`
 
 
 Interactive documentation

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`

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 <usage/routing/overview:Registering Routes>`
 
 
 Startup and Shutdown

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``

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 <autodiscovery>`_.
+If you don't pass the ``--app`` flag, the application will be automatically discovered, as explained in
+`Autodiscovery`_.
 
 Options
 ~~~~~~~

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`

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 <litestar.middleware.session.client_side.CookieBackendConfig>`
+ * :class:`CookieBackendConfig <litestar.middleware.session.client_side.CookieBackendConfig>`
 
 
 Server-side sessions
@@ -296,5 +296,5 @@ and load the appropriate data from the store
 
 .. seealso::
 
- - :doc:`/usage/stores`
- - :class:`ServerSideSessionConfig <litestar.middleware.session.server_side.ServerSideSessionConfig>`
+ * :doc:`/usage/stores`
+ * :class:`ServerSideSessionConfig <litestar.middleware.session.server_side.ServerSideSessionConfig>`