docs: add initial API docs

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,186 @@
+# Configuration file for the Sphinx documentation builder.
+from __future__ import annotations
+
+import os
+
+from litestar_saq.__metadata__ import __project__ as project
+from litestar_saq.__metadata__ import __version__ as version
+
+# -- Environmental Data ------------------------------------------------------
+
+
+# -- Project information -----------------------------------------------------
+project = project  # noqa: PLW0127
+author = "Cody Fincher"
+release = version
+release = os.getenv("_LITESTAR-SAQ_DOCS_BUILD_VERSION", version.rsplit(".")[0])
+copyright = "2023, Cody Fincher"  # noqa: A001
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "docs.fix_missing_references",
+    "sphinx_copybutton",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinx_click",
+    "sphinx_toolbox.collapse",
+    "sphinx_design",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "litestar": ("https://docs.litestar.dev/latest/", None),
+    "redis": ("https://redis.readthedocs.io/en/stable/", None),
+    "click": ("https://click.palletsprojects.com/en/latest/", None),
+    "saq": ("https://saq-py.readthedocs.io/en/latest/", None),
+}
+PY_CLASS = "py:class"
+PY_RE = r"py:.*"
+PY_METH = "py:meth"
+PY_ATTR = "py:attr"
+PY_OBJ = "py:obj"
+
+nitpicky = True
+nitpick_ignore = [
+    # external library / undocumented external
+    (PY_CLASS, "ExternalType"),
+    (PY_CLASS, "TypeEngine"),
+    (PY_CLASS, "UserDefinedType"),
+    (PY_CLASS, "dto.base_dto.AbstractDTO"),
+    (PY_CLASS, "di.Provide"),
+    (PY_CLASS, "Dependencies"),
+    (PY_CLASS, "connection.Request"),
+    (PY_CLASS, "BaseLoggingConfig"),
+    (PY_CLASS, "Litestar"),
+    (PY_METH, "type_engine"),
+    # type vars and aliases / intentionally undocumented
+    (PY_CLASS, "CollectionT"),
+    (PY_CLASS, "EmptyType"),
+    (PY_CLASS, "ModelT"),
+    (PY_CLASS, "T"),
+    (PY_CLASS, "State"),
+    (PY_CLASS, "AbstractDTO"),
+    (PY_CLASS, "Middleware"),
+    (PY_CLASS, "OptionalSequence"),
+    (PY_CLASS, "Router"),
+    (PY_CLASS, "router.Router"),
+    (PY_CLASS, "Parameter"),
+    (PY_CLASS, "response.Response"),
+    (PY_CLASS, "Response"),
+    (PY_CLASS, "config.app.AppConfig"),
+    (PY_CLASS, "AppConfig"),
+    (PY_CLASS, "Group"),
+    (PY_CLASS, "TypeDecodersSequence"),
+    (PY_CLASS, "TypeEncodersMap"),
+    (PY_CLASS, "SecurityRequirement"),
+    (PY_CLASS, "datastructures.ResponseHeader"),
+    (PY_CLASS, "ResponseCookies"),
+    (PY_CLASS, "datastructures.Cookie"),
+    (PY_CLASS, "ResponseHeaders"),
+    (PY_CLASS, "params.Parameter"),
+    (PY_CLASS, "dto.base_dto.AbstractDTO"),
+    (PY_ATTR, "serialization.encode_json"),
+    (PY_ATTR, "serialization.decode_json"),
+]
+nitpick_ignore_regex = [
+    (PY_RE, r"litestar_saq.*\.T"),
+    (PY_RE, r"saq.*"),
+    (PY_RE, r"types.*"),
+]
+
+napoleon_google_docstring = True
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = False
+napoleon_attr_annotations = True
+
+autoclass_content = "class"
+autodoc_class_signature = "separated"
+autodoc_default_options = {"special-members": "__init__", "show-inheritance": True, "members": True}
+autodoc_member_order = "bysource"
+autodoc_typehints_format = "short"
+autodoc_type_aliases: dict[str, str] = {}
+
+autosectionlabel_prefix_document = True
+
+todo_include_todos = True
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Style configuration -----------------------------------------------------
+html_theme = "shibuya"
+html_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
+html_show_sourcelink = True
+html_title = "Docs"
+html_favicon = "_static/logo.png"
+html_logo = "_static/logo.png"
+html_context = {
+    "source_type": "github",
+    "source_user": "cofin",
+    "source_repo": project.replace("_", "-"),
+}
+
+brand_colors = {
+    "--brand-primary": {"rgb": "245, 0, 87", "hex": "#f50057"},
+    "--brand-secondary": {"rgb": "32, 32, 32", "hex": "#202020"},
+    "--brand-tertiary": {"rgb": "161, 173, 161", "hex": "#A1ADA1"},
+    "--brand-green": {"rgb": "0, 245, 151", "hex": "#00f597"},
+    "--brand-alert": {"rgb": "243, 96, 96", "hex": "#f36060"},
+    "--brand-dark": {"rgb": "0, 0, 0", "hex": "#000000"},
+    "--brand-light": {"rgb": "235, 221, 221", "hex": "#ebdddd"},
+}
+
+html_theme_options = {
+    "logo_target": "/",
+    "announcement": "This documentation is currently under development.",
+    "github_url": "https://github.com/cofin/litestar-saq",
+    "nav_links": [
+        {"title": "Home", "url": "https://cofin.github.io/litesatr-asyncpg/"},
+        {"title": "Docs", "url": "https://cofin.github.io/litesatr-asyncpg/latest/"},
+        {"title": "Code", "url": "https://github.com/cofin/litestar-saq"},
+    ],
+    "light_css_variables": {
+        # RGB
+        "--sy-rc-theme": brand_colors["--brand-primary"]["rgb"],
+        "--sy-rc-text": brand_colors["--brand-primary"]["rgb"],
+        "--sy-rc-invert": brand_colors["--brand-primary"]["rgb"],
+        # "--sy-rc-bg": brand_colors["--brand-secondary"]["rgb"],
+        # Hex
+        "--sy-c-link": brand_colors["--brand-secondary"]["hex"],
+        # "--sy-c-foot-bg": "#191919",
+        "--sy-c-foot-divider": brand_colors["--brand-primary"]["hex"],
+        "--sy-c-foot-text": brand_colors["--brand-dark"]["hex"],
+        "--sy-c-bold": brand_colors["--brand-primary"]["hex"],
+        "--sy-c-heading": brand_colors["--brand-primary"]["hex"],
+        "--sy-c-text-weak": brand_colors["--brand-primary"]["hex"],
+        "--sy-c-text": brand_colors["--brand-dark"]["hex"],
+        "--sy-c-bg-weak": brand_colors["--brand-dark"]["rgb"],
+    },
+    "dark_css_variables": {
+        # RGB
+        "--sy-rc-theme": brand_colors["--brand-primary"]["rgb"],
+        "--sy-rc-text": brand_colors["--brand-primary"]["rgb"],
+        "--sy-rc-invert": brand_colors["--brand-primary"]["rgb"],
+        "--sy-rc-bg": brand_colors["--brand-dark"]["rgb"],
+        # Hex
+        "--sy-c-link": brand_colors["--brand-primary"]["hex"],
+        "--sy-c-foot-bg": brand_colors["--brand-dark"]["hex"],
+        "--sy-c-foot-divider": brand_colors["--brand-primary"]["hex"],
+        "--sy-c-foot-text": brand_colors["--brand-light"]["hex"],
+        "--sy-c-bold": brand_colors["--brand-primary"]["hex"],
+        "--sy-c-heading": brand_colors["--brand-primary"]["hex"],
+        "--sy-c-text-weak": brand_colors["--brand-primary"]["hex"],
+        "--sy-c-text": brand_colors["--brand-light"]["hex"],
+        "--sy-c-bg-weak": brand_colors["--brand-dark"]["hex"],
+        "--sy-c-bg": brand_colors["--brand-primary"]["hex"],
+    },
+}

docs/contribution-guide.rst

@@ -0,0 +1,3 @@
+:orphan:
+
+.. include:: ../CONTRIBUTING.rst

docs/fix_missing_references.py

@@ -0,0 +1,34 @@
+from __future__ import annotations  # noqa: INP001
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from docutils.nodes import Element
+    from sphinx.addnodes import pending_xref
+    from sphinx.application import Sphinx
+    from sphinx.environment import BuildEnvironment
+
+
+def on_missing_reference(app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: Element) -> Any:
+    if not hasattr(node, "attributes"):
+        return None
+
+    attributes = node.attributes
+    target = attributes["reftarget"]
+    py_domain = env.domains["py"]
+
+    # autodoc sometimes incorrectly resolves these types, so we try to resolve them as py:data fist and fall back to any
+    new_node = py_domain.resolve_xref(env, node["refdoc"], app.builder, "data", target, node, contnode)
+    if new_node is None:
+        resolved_xrefs = py_domain.resolve_any_xref(env, node["refdoc"], app.builder, target, node, contnode)
+        for ref in resolved_xrefs:
+            if ref:
+                return ref[1]
+    return new_node
+
+
+def setup(app: Sphinx) -> dict[str, bool]:
+    app.connect("missing-reference", on_missing_reference)
+    app.add_config_value("ignore_missing_refs", default={}, rebuild=False)
+
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

docs/index.rst

@@ -0,0 +1,56 @@
+============
+Litestar SAQ
+============
+
+Litestar SAQ is a plugin to manage SAQ background worker processes with your Litestar application
+
+
+Installation
+------------
+
+Installing ``litestar-saq`` is as easy as calling your favorite Python package manager:
+
+.. tab-set::
+
+    .. tab-item:: pip
+        :sync: key1
+
+        .. code-block:: bash
+            :caption: Using pip
+
+            python3 -m pip install litestar-saq
+
+    .. tab-item:: pdm
+
+        .. code-block:: bash
+            :caption: Using `PDM <https://pdm.fming.dev/>`_
+
+            pdm add litestar-saq
+
+    .. tab-item:: Poetry
+
+        .. code-block:: bash
+            :caption: Using `Poetry <https://python-poetry.org/>`_
+
+            poetry add litestar-saq
+
+Usage
+-----
+
+.. todo:: Add usage instructions
+
+.. toctree::
+    :titlesonly:
+    :caption: Litestar Asyncpg Documentation
+    :hidden:
+
+    usage/index
+    reference/index
+
+.. toctree::
+    :titlesonly:
+    :caption: Development
+    :hidden:
+
+    changelog
+    contribution-guide

docs/reference/base.rst

@@ -0,0 +1,6 @@
+====
+base
+====
+
+.. automodule:: litestar_saq.base
+    :members:

docs/reference/cli.rst

@@ -0,0 +1,6 @@
+===
+cli
+===
+
+.. automodule:: litestar_saq.cli
+    :members:

docs/reference/config.rst

@@ -0,0 +1,6 @@
+======
+config
+======
+
+.. automodule:: litestar_saq.config
+    :members:

docs/reference/controllers.rst

@@ -0,0 +1,6 @@
+===========
+controllers
+===========
+
+.. automodule:: litestar_saq.controllers
+    :members:

docs/reference/exceptions copy.rst

@@ -0,0 +1,6 @@
+==========
+exceptions
+==========
+
+.. automodule:: litestar_saq.exceptions
+    :members:

docs/reference/exceptions.rst

@@ -0,0 +1,6 @@
+==========
+exceptions
+==========
+
+.. automodule:: litestar_saq.exceptions
+    :members:

docs/reference/index.rst

@@ -0,0 +1,14 @@
+=========
+Reference
+=========
+
+The API documentation is for end users of the library. It provides an high-level
+overview of what features are available and how to use them.
+
+
+
+.. toctree::
+    :titlesonly:
+    :glob:
+
+    *

docs/reference/info.rst

@@ -0,0 +1,6 @@
+====
+info
+====
+
+.. automodule:: litestar_saq.info
+    :members:

docs/reference/plugin.rst

@@ -0,0 +1,6 @@
+======
+plugin
+======
+
+.. automodule:: litestar_saq.plugin
+    :members:

docs/reference/util.rst

@@ -0,0 +1,6 @@
+====
+util
+====
+
+.. automodule:: litestar_saq.util
+    :members:

docs/usage/index.rst

@@ -0,0 +1,14 @@
+=====
+Usage
+=====
+
+The usage documentation is for end users of the library. It provides an high-level
+overview of what features are available and how to use them.
+
+
+
+.. toctree::
+    :titlesonly:
+    :glob:
+
+    *