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)