docs: Added basic sphinx generation setup

.gitignore

@@ -28,3 +28,12 @@ coverage.xml
 
 # AI Tools
 .claude/
+
+# Sphinx
+sphinx/_build/
+sphinx/autoapi/
+
+# Only the page JSON is committed. Everything else Sphinx writes there is not.
+sphinx/json/*
+!sphinx/json/autoapi
+!sphinx/json/index.fjson

pyproject.toml

@@ -31,6 +31,13 @@ pytest-httpx = "^0.35.0"
 ruff = ">=0.1"
 freezegun = "^1.5.5"
 
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+sphinx = { version = "8.1.3", python = ">=3.10" }
+sphinx-autoapi = { version = ">=3.4,<4", python = ">=3.10" }
+
 [tool.pytest.ini_options]
 addopts = "--cov=src --cov-report=term-missing:skip-covered --cov-report=xml"
 

sphinx/Makefile

@@ -0,0 +1,20 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+BUILDDIR      = $(SOURCEDIR)_build
+JSONDIR       = $(SOURCEDIR)json
+
+.PHONY: help html json clean
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+json:
+	@$(SPHINXBUILD) -b json "$(SOURCEDIR)" "$(JSONDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	rm -rf "$(SOURCEDIR)autoapi"

sphinx/conf.py

@@ -0,0 +1,10 @@
+import os
+
+project = "auth0-api-python"
+with open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".version")) as _version_file:
+    release = _version_file.read().strip()
+
+extensions = ["autoapi.extension", "sphinx.ext.napoleon"]
+
+autoapi_dirs = ["../src"]
+autoapi_options = ["members", "undoc-members", "show-inheritance", "show-module-summary"]

sphinx/index.rst

@@ -0,0 +1,5 @@
+auth0-api-python
+================
+
+.. toctree::
+   :hidden:

sphinx/json/autoapi/auth0_api_python/act/index.fjson

@@ -0,0 +1 @@
+{"parents": [{"link": "../../", "title": "API Reference"}, {"link": "../", "title": "auth0_api_python"}], "prev": {"link": "../", "title": "auth0_api_python"}, "next": {"link": "../api_client/", "title": "auth0_api_python.api_client"}, "title": "auth0_api_python.act", "meta": null, "body": "<section id=\"module-auth0_api_python.act\">\n<span id=\"auth0-api-python-act\"></span><h1>auth0_api_python.act<a class=\"headerlink\" href=\"#module-auth0_api_python.act\" title=\"Link to this heading\">\u00b6</a></h1>\n<p>Helpers for working with the <cite>act</cite> claim on verified access token claims.</p>\n<section id=\"attributes\">\n<h2>Attributes<a class=\"headerlink\" href=\"#attributes\" title=\"Link to this heading\">\u00b6</a></h2>\n<table class=\"autosummary longtable docutils align-default\">\n<tbody>\n<tr class=\"row-odd\"><td><p><a class=\"reference internal\" href=\"#auth0_api_python.act.INVALID_ACT_CLAIM_MESSAGE\" title=\"auth0_api_python.act.INVALID_ACT_CLAIM_MESSAGE\"><code class=\"xref py py-obj docutils literal notranslate\"><span class=\"pre\">INVALID_ACT_CLAIM_MESSAGE</span></code></a></p></td>\n<td><p></p></td>\n</tr>\n</tbody>\n</table>\n</section>\n<section id=\"functions\">\n<h2>Functions<a class=\"headerlink\" href=\"#functions\" title=\"Link to this heading\">\u00b6</a></h2>\n<table class=\"autosummary longtable docutils align-default\">\n<tbody>\n<tr class=\"row-odd\"><td><p><a class=\"reference internal\" href=\"#auth0_api_python.act.get_current_actor\" title=\"auth0_api_python.act.get_current_actor\"><code class=\"xref py py-obj docutils literal notranslate\"><span class=\"pre\">get_current_actor</span></code></a>(\u2192\u00a0Optional[str])</p></td>\n<td><p>Return the current actor from the outermost <cite>act.sub</cite>, if present.</p></td>\n</tr>\n<tr class=\"row-even\"><td><p><a class=\"reference internal\" href=\"#auth0_api_python.act.get_delegation_chain\" title=\"auth0_api_python.act.get_delegation_chain\"><code class=\"xref py py-obj docutils literal notranslate\"><span class=\"pre\">get_delegation_chain</span></code></a>(\u2192\u00a0list[str])</p></td>\n<td><p>Return the delegation chain from newest actor to oldest actor.</p></td>\n</tr>\n</tbody>\n</table>\n</section>\n<section id=\"module-contents\">\n<h2>Module Contents<a class=\"headerlink\" href=\"#module-contents\" title=\"Link to this heading\">\u00b6</a></h2>\n<dl class=\"py data\">\n<dt class=\"sig sig-object py\" id=\"auth0_api_python.act.INVALID_ACT_CLAIM_MESSAGE\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">auth0_api_python.act.</span></span><span class=\"sig-name descname\"><span class=\"pre\">INVALID_ACT_CLAIM_MESSAGE</span></span><em class=\"property\"><span class=\"w\"> </span><span class=\"p\"><span class=\"pre\">=</span></span><span class=\"w\"> </span><span class=\"pre\">'Invalid</span> <span class=\"pre\">act</span> <span class=\"pre\">claim'</span></em><a class=\"headerlink\" href=\"#auth0_api_python.act.INVALID_ACT_CLAIM_MESSAGE\" title=\"Link to this definition\">\u00b6</a></dt>\n<dd></dd></dl>\n\n<dl class=\"py function\">\n<dt class=\"sig sig-object py\" id=\"auth0_api_python.act.get_current_actor\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">auth0_api_python.act.</span></span><span class=\"sig-name descname\"><span class=\"pre\">get_current_actor</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">claims</span></span><span class=\"p\"><span class=\"pre\">:</span></span><span class=\"w\"> </span><span class=\"n\"><span class=\"pre\">collections.abc.Mapping</span><span class=\"p\"><span class=\"pre\">[</span></span><span class=\"pre\">str</span><span class=\"p\"><span class=\"pre\">,</span></span><span class=\"w\"> </span><span class=\"pre\">Any</span><span class=\"p\"><span class=\"pre\">]</span></span></span></em><span class=\"sig-paren\">)</span> <span class=\"sig-return\"><span class=\"sig-return-icon\">&#x2192;</span> <span class=\"sig-return-typehint\"><span class=\"pre\">str</span><span class=\"w\"> </span><span class=\"p\"><span class=\"pre\">|</span></span><span class=\"w\"> </span><span class=\"pre\">None</span></span></span><a class=\"headerlink\" href=\"#auth0_api_python.act.get_current_actor\" title=\"Link to this definition\">\u00b6</a></dt>\n<dd><p>Return the current actor from the outermost <cite>act.sub</cite>, if present.</p>\n<p>Only the outermost <cite>act.sub</cite> should be used for authorization decisions.\nNested <cite>act</cite> values represent prior actors and are informational.</p>\n</dd></dl>\n\n<dl class=\"py function\">\n<dt class=\"sig sig-object py\" id=\"auth0_api_python.act.get_delegation_chain\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">auth0_api_python.act.</span></span><span class=\"sig-name descname\"><span class=\"pre\">get_delegation_chain</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">claims</span></span><span class=\"p\"><span class=\"pre\">:</span></span><span class=\"w\"> </span><span class=\"n\"><span class=\"pre\">collections.abc.Mapping</span><span class=\"p\"><span class=\"pre\">[</span></span><span class=\"pre\">str</span><span class=\"p\"><span class=\"pre\">,</span></span><span class=\"w\"> </span><span class=\"pre\">Any</span><span class=\"p\"><span class=\"pre\">]</span></span></span></em><span class=\"sig-paren\">)</span> <span class=\"sig-return\"><span class=\"sig-return-icon\">&#x2192;</span> <span class=\"sig-return-typehint\"><span class=\"pre\">list</span><span class=\"p\"><span class=\"pre\">[</span></span><span class=\"pre\">str</span><span class=\"p\"><span class=\"pre\">]</span></span></span></span><a class=\"headerlink\" href=\"#auth0_api_python.act.get_delegation_chain\" title=\"Link to this definition\">\u00b6</a></dt>\n<dd><p>Return the delegation chain from newest actor to oldest actor.</p>\n<p>The first entry is the current actor (outermost <cite>act.sub</cite>). Later entries are\nprior actors from nested <cite>act</cite> values and are typically most useful for audit\nand attribution.</p>\n</dd></dl>\n\n</section>\n</section>\n", "metatags": "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n", "rellinks": [["genindex", "General Index", "I", "index"], ["py-modindex", "Python Module Index", "", "modules"], ["autoapi/auth0_api_python/api_client/index", "auth0_api_python.api_client", "N", "next"], ["autoapi/auth0_api_python/index", "auth0_api_python", "P", "previous"]], "sourcename": "autoapi/auth0_api_python/act/index.rst.txt", "toc": "<ul>\n<li><a class=\"reference internal\" href=\"#\">auth0_api_python.act</a><ul>\n<li><a class=\"reference internal\" href=\"#attributes\">Attributes</a></li>\n<li><a class=\"reference internal\" href=\"#functions\">Functions</a></li>\n<li><a class=\"reference internal\" href=\"#module-contents\">Module Contents</a><ul>\n<li><a class=\"reference internal\" href=\"#auth0_api_python.act.INVALID_ACT_CLAIM_MESSAGE\"><code class=\"docutils literal notranslate\"><span class=\"pre\">INVALID_ACT_CLAIM_MESSAGE</span></code></a></li>\n<li><a class=\"reference internal\" href=\"#auth0_api_python.act.get_current_actor\"><code class=\"docutils literal notranslate\"><span class=\"pre\">get_current_actor()</span></code></a></li>\n<li><a class=\"reference internal\" href=\"#auth0_api_python.act.get_delegation_chain\"><code class=\"docutils literal notranslate\"><span class=\"pre\">get_delegation_chain()</span></code></a></li>\n</ul>\n</li>\n</ul>\n</li>\n</ul>\n", "display_toc": true, "page_source_suffix": ".rst", "current_page_name": "autoapi/auth0_api_python/act/index", "sidebars": ["about.html", "searchfield.html", "navigation.html", "relations.html", "donate.html"], "alabaster_version": "1.0.0", "alabaster_version_info": [1, 0, 0]}

sphinx/json/autoapi/auth0_api_python/encryption/index.fjson

@@ -0,0 +1 @@
+{"parents": [{"link": "../../", "title": "API Reference"}, {"link": "../", "title": "auth0_api_python"}], "prev": {"link": "../config/", "title": "auth0_api_python.config"}, "next": {"link": "../errors/", "title": "auth0_api_python.errors"}, "title": "auth0_api_python.encryption", "meta": null, "body": "<section id=\"module-auth0_api_python.encryption\">\n<span id=\"auth0-api-python-encryption\"></span><h1>auth0_api_python.encryption<a class=\"headerlink\" href=\"#module-auth0_api_python.encryption\" title=\"Link to this heading\">\u00b6</a></h1>\n<p>JWE encryption helpers for token store implementations.</p>\n<section id=\"functions\">\n<h2>Functions<a class=\"headerlink\" href=\"#functions\" title=\"Link to this heading\">\u00b6</a></h2>\n<table class=\"autosummary longtable docutils align-default\">\n<tbody>\n<tr class=\"row-odd\"><td><p><a class=\"reference internal\" href=\"#auth0_api_python.encryption.encrypt\" title=\"auth0_api_python.encryption.encrypt\"><code class=\"xref py py-obj docutils literal notranslate\"><span class=\"pre\">encrypt</span></code></a>(\u2192\u00a0str)</p></td>\n<td><p>Encrypt a dict to a compact JWE string. A fresh random kid is generated per call.</p></td>\n</tr>\n<tr class=\"row-even\"><td><p><a class=\"reference internal\" href=\"#auth0_api_python.encryption.decrypt\" title=\"auth0_api_python.encryption.decrypt\"><code class=\"xref py py-obj docutils literal notranslate\"><span class=\"pre\">decrypt</span></code></a>(\u2192\u00a0dict[str,\u00a0Any])</p></td>\n<td><p>Decrypt a compact JWE string back to a dict.</p></td>\n</tr>\n</tbody>\n</table>\n</section>\n<section id=\"module-contents\">\n<h2>Module Contents<a class=\"headerlink\" href=\"#module-contents\" title=\"Link to this heading\">\u00b6</a></h2>\n<dl class=\"py function\">\n<dt class=\"sig sig-object py\" id=\"auth0_api_python.encryption.encrypt\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">auth0_api_python.encryption.</span></span><span class=\"sig-name descname\"><span class=\"pre\">encrypt</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">payload</span></span><span class=\"p\"><span class=\"pre\">:</span></span><span class=\"w\"> </span><span class=\"n\"><span class=\"pre\">dict</span><span class=\"p\"><span class=\"pre\">[</span></span><span class=\"pre\">str</span><span class=\"p\"><span class=\"pre\">,</span></span><span class=\"w\"> </span><span class=\"pre\">Any</span><span class=\"p\"><span class=\"pre\">]</span></span></span></em>, <em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">secret</span></span><span class=\"p\"><span class=\"pre\">:</span></span><span class=\"w\"> </span><span class=\"n\"><span class=\"pre\">str</span></span></em>, <em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">salt</span></span><span class=\"p\"><span class=\"pre\">:</span></span><span class=\"w\"> </span><span class=\"n\"><span class=\"pre\">str</span></span></em><span class=\"sig-paren\">)</span> <span class=\"sig-return\"><span class=\"sig-return-icon\">&#x2192;</span> <span class=\"sig-return-typehint\"><span class=\"pre\">str</span></span></span><a class=\"headerlink\" href=\"#auth0_api_python.encryption.encrypt\" title=\"Link to this definition\">\u00b6</a></dt>\n<dd><p>Encrypt a dict to a compact JWE string. A fresh random kid is generated per call.</p>\n</dd></dl>\n\n<dl class=\"py function\">\n<dt class=\"sig sig-object py\" id=\"auth0_api_python.encryption.decrypt\">\n<span class=\"sig-prename descclassname\"><span class=\"pre\">auth0_api_python.encryption.</span></span><span class=\"sig-name descname\"><span class=\"pre\">decrypt</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">data</span></span><span class=\"p\"><span class=\"pre\">:</span></span><span class=\"w\"> </span><span class=\"n\"><span class=\"pre\">str</span></span></em>, <em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">secret</span></span><span class=\"p\"><span class=\"pre\">:</span></span><span class=\"w\"> </span><span class=\"n\"><span class=\"pre\">str</span></span></em>, <em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">salt</span></span><span class=\"p\"><span class=\"pre\">:</span></span><span class=\"w\"> </span><span class=\"n\"><span class=\"pre\">str</span></span></em><span class=\"sig-paren\">)</span> <span class=\"sig-return\"><span class=\"sig-return-icon\">&#x2192;</span> <span class=\"sig-return-typehint\"><span class=\"pre\">dict</span><span class=\"p\"><span class=\"pre\">[</span></span><span class=\"pre\">str</span><span class=\"p\"><span class=\"pre\">,</span></span><span class=\"w\"> </span><span class=\"pre\">Any</span><span class=\"p\"><span class=\"pre\">]</span></span></span></span><a class=\"headerlink\" href=\"#auth0_api_python.encryption.decrypt\" title=\"Link to this definition\">\u00b6</a></dt>\n<dd><p>Decrypt a compact JWE string back to a dict.</p>\n</dd></dl>\n\n</section>\n</section>\n", "metatags": "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n", "rellinks": [["genindex", "General Index", "I", "index"], ["py-modindex", "Python Module Index", "", "modules"], ["autoapi/auth0_api_python/errors/index", "auth0_api_python.errors", "N", "next"], ["autoapi/auth0_api_python/config/index", "auth0_api_python.config", "P", "previous"]], "sourcename": "autoapi/auth0_api_python/encryption/index.rst.txt", "toc": "<ul>\n<li><a class=\"reference internal\" href=\"#\">auth0_api_python.encryption</a><ul>\n<li><a class=\"reference internal\" href=\"#functions\">Functions</a></li>\n<li><a class=\"reference internal\" href=\"#module-contents\">Module Contents</a><ul>\n<li><a class=\"reference internal\" href=\"#auth0_api_python.encryption.encrypt\"><code class=\"docutils literal notranslate\"><span class=\"pre\">encrypt()</span></code></a></li>\n<li><a class=\"reference internal\" href=\"#auth0_api_python.encryption.decrypt\"><code class=\"docutils literal notranslate\"><span class=\"pre\">decrypt()</span></code></a></li>\n</ul>\n</li>\n</ul>\n</li>\n</ul>\n", "display_toc": true, "page_source_suffix": ".rst", "current_page_name": "autoapi/auth0_api_python/encryption/index", "sidebars": ["about.html", "searchfield.html", "navigation.html", "relations.html", "donate.html"], "alabaster_version": "1.0.0", "alabaster_version_info": [1, 0, 0]}

sphinx/json/autoapi/auth0_api_python/index.fjson

@@ -0,0 +1 @@
+{"parents": [{"link": "../", "title": "API Reference"}], "prev": {"link": "../", "title": "API Reference"}, "next": {"link": "act/", "title": "auth0_api_python.act"}, "title": "auth0_api_python", "meta": null, "body": "<section id=\"module-auth0_api_python\">\n<span id=\"auth0-api-python\"></span><h1>auth0_api_python<a class=\"headerlink\" href=\"#module-auth0_api_python\" title=\"Link to this heading\">\u00b6</a></h1>\n<p>auth0-api-python</p>\n<p>A lightweight Python SDK for verifying Auth0-issued access tokens\nin server-side APIs, using Authlib for OIDC discovery and JWKS fetching.</p>\n<section id=\"submodules\">\n<h2>Submodules<a class=\"headerlink\" href=\"#submodules\" title=\"Link to this heading\">\u00b6</a></h2>\n<div class=\"toctree-wrapper compound\">\n<ul>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"act/\">auth0_api_python.act</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"api_client/\">auth0_api_python.api_client</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"cache/\">auth0_api_python.cache</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"config/\">auth0_api_python.config</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"encryption/\">auth0_api_python.encryption</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"errors/\">auth0_api_python.errors</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"telemetry/\">auth0_api_python.telemetry</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"token_store/\">auth0_api_python.token_store</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"token_utils/\">auth0_api_python.token_utils</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"types/\">auth0_api_python.types</a></li>\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"utils/\">auth0_api_python.utils</a></li>\n</ul>\n</div>\n</section>\n</section>\n", "metatags": "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n", "rellinks": [["genindex", "General Index", "I", "index"], ["py-modindex", "Python Module Index", "", "modules"], ["autoapi/auth0_api_python/act/index", "auth0_api_python.act", "N", "next"], ["autoapi/index", "API Reference", "P", "previous"]], "sourcename": "autoapi/auth0_api_python/index.rst.txt", "toc": "<ul>\n<li><a class=\"reference internal\" href=\"#\">auth0_api_python</a><ul>\n<li><a class=\"reference internal\" href=\"#submodules\">Submodules</a></li>\n</ul>\n</li>\n</ul>\n", "display_toc": true, "page_source_suffix": ".rst", "current_page_name": "autoapi/auth0_api_python/index", "sidebars": ["about.html", "searchfield.html", "navigation.html", "relations.html", "donate.html"], "alabaster_version": "1.0.0", "alabaster_version_info": [1, 0, 0]}