chore(release)!: Version 3.0

.github/workflows/docs.yml

@@ -36,15 +36,15 @@ jobs:
         run: git fetch origin gh-pages --depth=1
 
       - name: Build release docs
-        run: pdm run python tools/build_docs.py docs-build
+        run: pdm run python tools/build_docs.py docs-build --environment 2
         if: github.event_name == 'release'
 
       - name: Build docs (main branch)
-        run: pdm run python tools/build_docs.py docs-build --version main
+        run: pdm run python tools/build_docs.py docs-build --version main --environment development
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
 
       - name: Build docs (v3.0 branch)
-        run: pdm run python tools/build_docs.py docs-build --version 3-dev
+        run: pdm run python tools/build_docs.py docs-build --version 3-dev --environment v3-development
         if: github.event_name == 'push' && github.ref == 'refs/heads/v3.0'
 
       - name: Deploy

docs/_static/style.css

@@ -25,9 +25,9 @@
   color: #f55353;
 }
 
-p {
-  font-size: 1.1em;
-}
+/*p {*/
+/*  font-size: 1.1em;*/
+/*}*/
 
 html[data-theme="dark"] .mermaid svg {
   background-color: white;

docs/_static/tables/framework-comparison.csv

@@ -0,0 +1,16 @@
+Feature,Litestar,FastAPI,Starlette,Sanic,Quart
+OpenAPI,:octicon:`check`,:octicon:`check`,-,-,-
+Automatic API documentation,"Swagger, ReDoc, Stoplight Elements","Swagger, ReDoc",-,-,-
+Data validation,:octicon:`check`,:octicon:`check`,-,-,-
+Dependency Injection,:octicon:`check`,:octicon:`check`,-,:octicon:`check`,-
+Class based routing,:octicon:`check`,Extension,:octicon:`check`,:octicon:`check`,:octicon:`check`
+ORM integration,"SQLAlchemy, Tortoise, Piccolo",-,-,-,Extension
+Templating,"Jinja, Mako",Jinja,Jinja,Jinja,Jinja
+MessagePack,:octicon:`check`,-,-,-,-
+CORS,:octicon:`check`,:octicon:`check`,:octicon:`check`,:octicon:`check`,Extension
+CSRF,:octicon:`check`,-,-,-,-
+Rate-limiting,:octicon:`check`,-,-,Extension,-
+JWT,:octicon:`check`,-,-,-,-
+Sessions,:octicon:`check`,Client-side,Client-side,-,Client-side
+Authentication,JWT / Session based,-,-,-,-
+Caching,:octicon:`check`,-,-,-,-

docs/_static/versioning.js

@@ -21,13 +21,15 @@ const addVersionWarning = (currentVersion, latestVersion) => {
   const container = document.createElement("div");
   container.id = "version-warning";
 
-  const warningText = document.createElement("span");
-  warningText.textContent = `You are viewing the documentation for ${
-    currentVersion === "dev" ||
-    parseInt(currentVersion) > parseInt(latestVersion)
-      ? "a preview"
-      : "an outdated"
-  } version of Litestar.`;
+  const isPreviewVersion = (version) => {
+        const previewVersions = ['dev', 'develop', 'main', '3-dev'];
+        return previewVersions.includes(version) || parseInt(version) > parseInt(latestVersion);
+    };
+
+    const warningText = document.createElement("span");
+    warningText.textContent = `You are viewing the documentation for ${
+        isPreviewVersion(currentVersion) ? "a preview" : "an outdated"
+    } version of Litestar.`;
   container.appendChild(warningText);
 
   const latestLink = document.createElement("a");

docs/conf.py

@@ -4,6 +4,7 @@
 import os
 import re
 import warnings
+from datetime import datetime
 from functools import partial
 from typing import Any
 
@@ -22,10 +23,16 @@
 PY_OBJ = "py:obj"
 PY_FUNC = "py:func"
 
+current_year = datetime.now().year
 project = "Litestar"
-copyright = "2024, Litestar-Org"
-author = "Litestar-Org"
+copyright = f"{current_year}, Litestar Organization"
+author = "Litestar Organization"
 release = os.getenv("_LITESTAR_DOCS_BUILD_VERSION", importlib.metadata.version("litestar").rsplit(".")[0])
+environment = os.getenv("_LITESTAR_DOCS_BUILD_ENVIRONMENT", "local")
+
+rst_epilog = f"""
+.. |version| replace:: {release}
+"""
 
 extensions = [
     "sphinx.ext.intersphinx",
@@ -39,6 +46,7 @@
     "sphinxcontrib.mermaid",
     "sphinx_click",
     "sphinx_paramlinks",
+    "sphinx_togglebutton",
 ]
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
@@ -126,7 +134,6 @@
     (PY_CLASS, "litestar.template.base.TemplateType_co"),
     (PY_CLASS, "litestar.template.base.ContextType_co"),
     (PY_CLASS, "litestar.template.base.R"),
-    (PY_ATTR, "litestar.openapi.controller.OpenAPIController.swagger_ui_init_oauth"),
     # intentionally undocumented
     (PY_CLASS, "BacklogStrategy"),
     (PY_CLASS, "ExceptionT"),
@@ -190,6 +197,8 @@
     ("py:exc", "HTTPExceptions"),
     (PY_CLASS, "litestar.template.Template"),
     (PY_CLASS, "litestar.middleware.compression.gzip_facade.GzipCompression"),
+    (PY_CLASS, "litestar.openapi.OpenAPIController"),
+    (PY_CLASS, "openapi.controller.OpenAPIController"),
     (PY_CLASS, "litestar.handlers.http_handlers.decorators._subclass_warning"),
 ]
 
@@ -219,6 +228,7 @@
     (PY_RE, r"advanced_alchemy\.config.common\.EngineT"),
     (PY_RE, r"advanced_alchemy\.config.common\.SessionT"),
     (PY_RE, r".*R"),
+    (PY_RE, r".*ScopeT"),
     (PY_OBJ, r"litestar.security.jwt.auth.TokenT"),
     (PY_CLASS, "ExceptionToProblemDetailMapType"),
     (PY_CLASS, "litestar.security.jwt.token.JWTDecodeOptions"),
@@ -232,7 +242,6 @@
     # No idea what autodoc is doing here. Possibly unfixable on our end
     "litestar.template.base.TemplateEngineProtocol.get_template": {"litestar.template.base.T_co"},
     "litestar.template": {"litestar.template.base.T_co"},
-    "litestar.openapi.OpenAPIController.security": {"SecurityRequirement"},
     "litestar.response.file.async_file_iterator": {"FileSystemAdapter"},
     "advanced_alchemy._listeners.touch_updated_timestamp": {"Session"},
     re.compile("litestar.response.redirect.*"): {"RedirectStatusType"},
@@ -256,7 +265,7 @@
 ]
 
 auto_pytabs_min_version = (3, 8)
-auto_pytabs_max_version = (3, 11)
+auto_pytabs_max_version = (3, 12)
 auto_pytabs_compat_mode = True
 
 autosectionlabel_prefix_document = True
@@ -266,78 +275,134 @@
     "ref.python",  # TODO: remove when https://github.com/sphinx-doc/sphinx/issues/4961 is fixed
 ]
 
+# -- Style configuration -----------------------------------------------------
 html_theme = "litestar_sphinx_theme"
+html_title = "Litestar Framework"
+pygments_style = "lightbulb"
+
 html_static_path = ["_static"]
+templates_path = ["_templates"]
 html_js_files = ["versioning.js"]
 html_css_files = ["style.css"]
-html_show_sourcelink = False
-html_title = "Litestar Framework"
+
+html_show_sourcelink = True  # TODO: this doesn't work :(
+html_copy_source = True
+
+html_context = {
+    "source_type": "github",
+    "source_user": "litestar-org",
+    "source_repo": "litestar",
+    # "source_version": "main",  # TODO: We should set this with an envvar depending on which branch we are building?
+    "current_version": "latest",  # TODO: Version dropdown only show caret and now text
+    "versions": [  # TODO(provinzkraut): this needs to use versions.json but im not 100% on how to do this yet
+        ("latest", "/latest"),
+        ("development", "/main"),
+        ("v3", "/3-dev"),
+        ("v2", "/2"),
+        ("v1", "/1"),
+    ],
+    "version": release,
+}
 
 html_theme_options = {
-    "use_page_nav": False,
+    "logo_target": "/",
     "github_repo_name": "litestar",
-    "logo": {
-        "link": "https://litestar.dev",
-    },
-    "pygment_light_style": "xcode",
-    "pygment_dark_style": "lightbulb",
     "navigation_with_keys": True,
-    "extra_navbar_items": {
-        "Documentation": "index",
-        "Community": {
-            "Contributing": {
-                "description": "Learn how to contribute to the Litestar project",
-                "link": "https://docs.litestar.dev/latest/contribution-guide.html",
-                "icon": "contributing",
-            },
-            "Code of Conduct": {
-                "description": "Review the etiquette for interacting with the Litestar community",
-                "link": "https://github.com/litestar-org/.github?tab=coc-ov-file",
-                "icon": "coc",
-            },
-            "Security": {
-                "description": "Overview of Litestar's security protocols",
-                "link": "https://github.com/litestar-org/.github?tab=coc-ov-file#security-ov-file",
-                "icon": "coc",
-            },
+    "nav_links": [  # TODO(provinzkraut): I need a guide on extra_navbar_items and its magic :P
+        {"title": "Home", "url": "index"},
+        {
+            "title": "Community",
+            "children": [
+                {
+                    "title": "Contributing",
+                    "summary": "Learn how to contribute to the Litestar project",
+                    "url": "contribution-guide",
+                    "icon": "contributing",
+                },
+                {
+                    "title": "Code of Conduct",
+                    "summary": "Review the etiquette for interacting with the Litestar community",
+                    "url": "https://github.com/litestar-org/.github?tab=coc-ov-file",
+                    "icon": "coc",
+                },
+                {
+                    "title": "Security",
+                    "summary": "Overview of Litestar's security protocols",
+                    "url": "https://github.com/litestar-org/.github?tab=coc-ov-file#security-ov-file",
+                    "icon": "coc",
+                },
+            ],
         },
-        "About": {
-            "Litestar Organization": {
-                "description": "Details about the Litestar organization",
-                "link": "https://litestar.dev/about/organization",
-                "icon": "org",
-            },
-            "Releases": {
-                "description": "Explore the release process, versioning, and deprecation policy for Litestar",
-                "link": "https://litestar.dev/about/litestar-releases",
-                "icon": "releases",
-            },
+        {
+            "title": "About",
+            "children": [
+                {
+                    "title": "Litestar Organization",
+                    "summary": "Details about the Litestar organization",
+                    "url": "https://litestar.dev/about/organization",
+                    "icon": "org",
+                },
+                {
+                    "title": "Releases",
+                    "summary": "Explore the release process, versioning, and deprecation policy for Litestar",
+                    "url": "https://litestar.dev/about/litestar-releases",
+                    "icon": "releases",
+                },
+            ],
         },
-        "Release notes": {
-            "What's new in 2.0": "release-notes/whats-new-2",
-            "2.x Changelog": "https://docs.litestar.dev/2/release-notes/changelog.html",
-            "1.x Changelog": "https://docs.litestar.dev/1/release-notes/changelog.html",
+        {
+            "title": "Release notes",
+            "children": [
+                {
+                    "title": "What's new in 3.0",
+                    "url": "release-notes/whats-new-3",
+                    "summary": "Explore the new features in Litestar 3.0",
+                },
+                {
+                    "title": "3.x Changelog",
+                    "url": "release-notes/changelog",
+                    "summary": "All changes in the 3.x series",
+                },
+                {
+                    "title": "2.x Changelog",
+                    "url": "https://docs.litestar.dev/2/release-notes/changelog.html",
+                    "summary": "All changes in the 2.x series",
+                },
+            ],
         },
-        "Help": {
-            "Discord Help Forum": {
-                "description": "Dedicated Discord help forum",
-                "link": "https://discord.gg/litestar",
-                "icon": "coc",
-            },
-            "GitHub Discussions": {
-                "description": "GitHub Discussions ",
-                "link": "https://github.com/orgs/litestar-org/discussions",
-                "icon": "coc",
-            },
-            "Stack Overflow": {
-                "description": "We monitor the <code><b>litestar</b></code> tag on Stack Overflow",
-                "link": "https://stackoverflow.com/questions/tagged/litestar",
-                "icon": "coc",
-            },
+        {
+            "title": "Help",
+            "children": [
+                {
+                    "title": "Discord Help Forum",
+                    "summary": "Dedicated Discord help forum",
+                    "url": "https://discord.gg/litestar",
+                    "icon": "coc",
+                },
+                {
+                    "title": "GitHub Discussions",
+                    "summary": "GitHub Discussions",
+                    "url": "https://github.com/orgs/litestar-org/discussions",
+                    "icon": "coc",
+                },
+                {
+                    "title": "Stack Overflow",
+                    "summary": "We monitor the <code><b>litestar</b></code> tag on Stack Overflow",
+                    "url": "https://stackoverflow.com/questions/tagged/litestar",
+                    "icon": "coc",
+                },
+            ],
         },
-    },
+        {"title": "Sponsor", "url": "https://github.com/sponsors/Litestar-Org", "icon": "heart"},
+    ],
 }
 
+if environment != "latest":  # TODO(provinzkraut): it'd be awesome to be able to use the builtin announcement banner
+    html_theme_options["announcement"] = (
+        f"You are viewing the <bold>{environment}</bold> version of the documentation. "
+        f"Click here to go to the latest version."
+    )
+
 
 def update_html_context(
     app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree: document
@@ -347,20 +412,18 @@ def update_html_context(
 
 def delayed_setup(app: Sphinx) -> None:
     """
-    When running linkcheck pydata_sphinx_theme causes a build failure, and checking
+    When running linkcheck Shibuya 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)  # type: ignore
+    app.setup_extension("shibuya")
+    # app.connect("html-page-context", update_html_context)  # TODO(provinkraut): fix
 
 
 def setup(app: Sphinx) -> dict[str, bool]:
-    app.connect("builder-inited", delayed_setup, priority=0)  # type: ignore
-
+    app.connect("builder-inited", delayed_setup, priority=0)# type: ignore
     app.setup_extension("litestar_sphinx_theme")
-
     return {"parallel_read_safe": True, "parallel_write_safe": True}

docs/examples/pagination/using_cursor_pagination.py

@@ -34,7 +34,7 @@ def get_items(self, cursor: Optional[str], results_per_page: int) -> Tuple[List[
 # we now create a regular handler. The handler will receive a single query parameter - 'cursor', which
 # we will pass to the paginator.
 @get("/people", sync_to_thread=False)
-def people_handler(cursor: Optional[str], results_per_page: int) -> CursorPagination[str, Person]:
+def people_handler(*, cursor: Optional[str] = None, results_per_page: int) -> CursorPagination[str, Person]:
     return paginator(cursor=cursor, results_per_page=results_per_page)