docs: add Sphinx JSON reference for the docs site

.gitignore

@@ -17,12 +17,24 @@ env/
 #Build files
 dist
 sphinx/_build
-sphinx/reference
+
+# autoapi writes the module sources next to conf.py. Only json/ is tracked.
+sphinx/*/
+!sphinx/json/
 
 # Only the page JSON is committed. Everything else Sphinx writes there is not.
-sphinx/json/*
-!sphinx/json/reference
-!sphinx/json/index.fjson
+sphinx/json/.buildinfo
+sphinx/json/.doctrees
+sphinx/json/_sources
+sphinx/json/_static
+sphinx/json/environment.pickle
+sphinx/json/genindex.fjson
+sphinx/json/globalcontext.json
+sphinx/json/last_build
+sphinx/json/objects.inv
+sphinx/json/py-modindex.fjson
+sphinx/json/search.fjson
+sphinx/json/searchindex.json
 
 #testfile
 server.py

sphinx/conf.py

@@ -27,7 +27,7 @@
 
 autoapi_dirs = ["../src"]
 autoapi_type = "python"
-autoapi_root = "reference"
+autoapi_root = "."
 autoapi_ignore = ["**/tests/**", "**/test_*.py"]
 
 autoapi_options = [
@@ -37,18 +37,13 @@
 ]
 autoapi_member_order = "groupwise"
 autoapi_keep_files = True
-autoapi_template_dir = "_templates/autoapi"
+autoapi_add_toctree_entry = False
 autoapi_python_class_content = "class"
 
-# Top-level import package, shown in each module's import block.
+# Top-level import package.
 IMPORT_ROOT = "auth0_server_python"
 
 
-def autoapi_prepare_jinja_env(jinja_env):
-    jinja_env.globals["import_root"] = IMPORT_ROOT
-
-
-
 def autoapi_skip_member(app, what, name, obj, skip, options):
     if what == "class" and name.endswith(".Config"):
         return True
@@ -63,7 +58,7 @@ def autoapi_skip_member(app, what, name, obj, skip, options):
 
 # -- Signatures ---------------------------------------------------------
 
-# Show `Name(...)` not `module.Name(...)`. The import block gives the full path.
+# Show `Name(...)` not `module.Name(...)`.
 add_module_names = False
 
 # -- Source links -------------------------------------------------------
@@ -116,9 +111,18 @@ def linkcode_resolve(domain, info):
 
 # -- General ------------------------------------------------------------
 
-templates_path = ["_templates"]
-
-exclude_patterns = ["_build", "_templates", "Thumbs.db", ".DS_Store"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    # Package pages only list their submodules.
+    "utils/index.rst",
+    "store/index.rst",
+    "encryption/index.rst",
+    "auth_server/index.rst",
+    "auth_server/anonymous/index.rst",
+    "auth_schemes/index.rst",
+]
 
 def _resolve_root_prefixed(app, env, node, contnode):
     """Resolve annotations that the default lookup misses.

sphinx/index.rst

@@ -1,8 +1,19 @@
 auth0-server-python
 ===================
 
-Auth0 server-side Python SDK: authentication flows, token management, and session handling
-for web applications.
+Install
+-------
+
+.. code-block:: shell
+
+   pip install auth0-server-python
+   # or, with Poetry
+   poetry add auth0-server-python
+
+* `Examples <https://github.com/auth0/auth0-server-python/blob/main/examples>`_
 
 .. toctree::
    :hidden:
+   :glob:
+
+   **

sphinx/json/auth_schemes/bearer_auth/index.fjson

@@ -0,0 +1 @@
+{"parents": [], "prev": {"link": "../../", "title": "auth0-server-python"}, "next": {"link": "../client_assertion/", "title": "auth_schemes.client_assertion"}, "title": "auth_schemes.bearer_auth", "meta": null, "body": "<section id=\"module-auth_schemes.bearer_auth\">\n<span id=\"auth-schemes-bearer-auth\"></span><h1>auth_schemes.bearer_auth<a class=\"headerlink\" href=\"#module-auth_schemes.bearer_auth\" title=\"Link to this heading\">\u00b6</a></h1>\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 class\">\n<dt class=\"sig sig-object py\" id=\"auth_schemes.bearer_auth.BearerAuth\">\n<em class=\"property\"><span class=\"pre\">class</span><span class=\"w\"> </span></em><span class=\"sig-name descname\"><span class=\"pre\">BearerAuth</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">token</span></span><span class=\"p\"><span class=\"pre\">:</span></span><span class=\"w\"> </span><span class=\"n\"><a class=\"reference external\" href=\"https://docs.python.org/3/builtins/stdtypes.html#str\" title=\"(in Python v3.15)\"><span class=\"pre\">str</span></a></span></em><span class=\"sig-paren\">)</span><a class=\"reference external\" href=\"https://github.com/auth0/auth0-server-python/blob/main/src/auth0_server_python/auth_schemes/bearer_auth.py#L4\"><span class=\"viewcode-link\"><span class=\"pre\">[source]</span></span></a><a class=\"headerlink\" href=\"#auth_schemes.bearer_auth.BearerAuth\" title=\"Link to this definition\">\u00b6</a></dt>\n<dd><p>Bases: <code class=\"xref py py-obj docutils literal notranslate\"><span class=\"pre\">httpx.Auth</span></code></p>\n<p>Base class for all authentication schemes.</p>\n<p>To implement a custom authentication scheme, subclass <cite>Auth</cite> and override\nthe <cite>.auth_flow()</cite> method.</p>\n<p>If the authentication scheme does I/O such as disk access or network calls, or uses\nsynchronization primitives such as locks, you should override <cite>.sync_auth_flow()</cite>\nand/or <cite>.async_auth_flow()</cite> instead of <cite>.auth_flow()</cite> to provide specialized\nimplementations that will be used by <cite>Client</cite> and <cite>AsyncClient</cite> respectively.</p>\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"auth_schemes.bearer_auth.BearerAuth.auth_flow\">\n<span class=\"sig-name descname\"><span class=\"pre\">auth_flow</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">request</span></span></em><span class=\"sig-paren\">)</span><a class=\"reference external\" href=\"https://github.com/auth0/auth0-server-python/blob/main/src/auth0_server_python/auth_schemes/bearer_auth.py#L8\"><span class=\"viewcode-link\"><span class=\"pre\">[source]</span></span></a><a class=\"headerlink\" href=\"#auth_schemes.bearer_auth.BearerAuth.auth_flow\" title=\"Link to this definition\">\u00b6</a></dt>\n<dd><p>Execute the authentication flow.</p>\n<p>To dispatch a request, <cite>yield</cite> it:</p>\n<p><code class=\"docutils literal notranslate\"><span class=\"pre\">`</span>\n<span class=\"pre\">yield</span> <span class=\"pre\">request</span>\n<span class=\"pre\">`</span></code></p>\n<p>The client will <cite>.send()</cite> the response back into the flow generator. You can\naccess it like so:</p>\n<p><code class=\"docutils literal notranslate\"><span class=\"pre\">`</span>\n<span class=\"pre\">response</span> <span class=\"pre\">=</span> <span class=\"pre\">yield</span> <span class=\"pre\">request</span>\n<span class=\"pre\">`</span></code></p>\n<p>A <cite>return</cite> (or reaching the end of the generator) will result in the\nclient returning the last response obtained from the server.</p>\n<p>You can dispatch as many requests as is necessary.</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"auth_schemes.bearer_auth.BearerAuth.token\">\n<span class=\"sig-name descname\"><span class=\"pre\">token</span></span><a class=\"headerlink\" href=\"#auth_schemes.bearer_auth.BearerAuth.token\" title=\"Link to this definition\">\u00b6</a></dt>\n<dd></dd></dl>\n\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"], ["auth_schemes/client_assertion/index", "auth_schemes.client_assertion", "N", "next"], ["index", "auth0-server-python", "P", "previous"]], "sourcename": "auth_schemes/bearer_auth/index.rst.txt", "toc": "<ul>\n<li><a class=\"reference internal\" href=\"#\">auth_schemes.bearer_auth</a><ul>\n<li><a class=\"reference internal\" href=\"#module-contents\">Module Contents</a><ul>\n<li><a class=\"reference internal\" href=\"#auth_schemes.bearer_auth.BearerAuth\"><code class=\"docutils literal notranslate\"><span class=\"pre\">BearerAuth</span></code></a><ul>\n<li><a class=\"reference internal\" href=\"#auth_schemes.bearer_auth.BearerAuth.auth_flow\"><code class=\"docutils literal notranslate\"><span class=\"pre\">BearerAuth.auth_flow()</span></code></a></li>\n<li><a class=\"reference internal\" href=\"#auth_schemes.bearer_auth.BearerAuth.token\"><code class=\"docutils literal notranslate\"><span class=\"pre\">BearerAuth.token</span></code></a></li>\n</ul>\n</li>\n</ul>\n</li>\n</ul>\n</li>\n</ul>\n", "display_toc": true, "page_source_suffix": ".rst", "current_page_name": "auth_schemes/bearer_auth/index", "sidebars": ["about.html", "navigation.html", "relations.html", "searchbox.html", "donate.html"], "alabaster_version": "0.7.16", "alabaster_version_info": [0, 7, 16]}