feat: mintlify poc server python

.gitignore

@@ -16,7 +16,13 @@ env/
 
 #Build files
 dist
-docs
+sphinx/_build
+sphinx/reference
+
+# Only the page JSON is committed. Everything else Sphinx writes there is not.
+sphinx/json/*
+!sphinx/json/reference
+!sphinx/json/index.fjson
 
 #testfile
 server.py

pyproject.toml

@@ -19,6 +19,10 @@ httpx = "^0.28.1"
 pydantic = "^2.10.6"
 jwcrypto = "^1.5.7"
 
+[tool.poetry.group.docs.dependencies]
+sphinx = ">=7.4,<9"
+sphinx-autoapi = ">=3.4,<4"
+
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.2"
 pytest-cov = "^4.0"

sphinx/Makefile

@@ -0,0 +1,22 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help Makefile html clean
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+json:
+	@$(SPHINXBUILD) -b json "$(SOURCEDIR)" "json" $(SPHINXOPTS) $(O)
+
+clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	rm -rf reference/
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

sphinx/_templates/autoapi/python/module.rst

@@ -0,0 +1,173 @@
+{% if obj.display %}
+   {% if is_own_page %}
+{{ obj.id }}
+{{ "=" * obj.id|length }}
+
+.. py:module:: {{ obj.name }}
+
+      {% if obj.docstring %}
+.. autoapi-nested-parse::
+
+   {{ obj.docstring|indent(3) }}
+
+      {% endif %}
+
+      {% block submodules %}
+         {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
+         {% set visible_submodules = obj.submodules|selectattr("display")|list %}
+         {% set visible_submodules = (visible_subpackages + visible_submodules)|sort %}
+         {% if visible_submodules %}
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+            {% for submodule in visible_submodules %}
+   {{ submodule.include_path }}
+            {% endfor %}
+
+
+         {% endif %}
+      {% endblock %}
+      {% block content %}
+         {% set visible_children = obj.children|selectattr("display")|list %}
+         {% if visible_children %}
+            {% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %}
+            {% if visible_attributes %}
+               {% if "attribute" in own_page_types or "show-module-summary" in autoapi_options %}
+Attributes
+----------
+
+                  {% if "attribute" in own_page_types %}
+.. toctree::
+   :hidden:
+
+                     {% for attribute in visible_attributes %}
+   {{ attribute.include_path }}
+                     {% endfor %}
+
+                  {% endif %}
+.. autoapisummary::
+
+                  {% for attribute in visible_attributes %}
+   {{ attribute.id }}
+                  {% endfor %}
+               {% endif %}
+
+
+            {% endif %}
+            {% set visible_exceptions = visible_children|selectattr("type", "equalto", "exception")|list %}
+            {% if visible_exceptions %}
+               {% if "exception" in own_page_types or "show-module-summary" in autoapi_options %}
+Exceptions
+----------
+
+                  {% if "exception" in own_page_types %}
+.. toctree::
+   :hidden:
+
+                     {% for exception in visible_exceptions %}
+   {{ exception.include_path }}
+                     {% endfor %}
+
+                  {% endif %}
+.. autoapisummary::
+
+                  {% for exception in visible_exceptions %}
+   {{ exception.id }}
+                  {% endfor %}
+               {% endif %}
+
+
+            {% endif %}
+            {% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
+            {% if visible_classes %}
+               {% if "class" in own_page_types or "show-module-summary" in autoapi_options %}
+Classes
+-------
+
+                  {% if "class" in own_page_types %}
+.. toctree::
+   :hidden:
+
+                     {% for klass in visible_classes %}
+   {{ klass.include_path }}
+                     {% endfor %}
+
+                  {% endif %}
+.. autoapisummary::
+
+                  {% for klass in visible_classes %}
+   {{ klass.id }}
+                  {% endfor %}
+               {% endif %}
+
+
+            {% endif %}
+            {% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
+            {% if visible_functions %}
+               {% if "function" in own_page_types or "show-module-summary" in autoapi_options %}
+Functions
+---------
+
+                  {% if "function" in own_page_types %}
+.. toctree::
+   :hidden:
+
+                     {% for function in visible_functions %}
+   {{ function.include_path }}
+                     {% endfor %}
+
+                  {% endif %}
+.. autoapisummary::
+
+                  {% for function in visible_functions %}
+   {{ function.id }}
+                  {% endfor %}
+               {% endif %}
+
+
+            {% endif %}
+            {% set this_page_children = visible_children|rejectattr("type", "in", own_page_types)|list %}
+            {% if this_page_children %}
+               {% set importable = this_page_children|selectattr("type", "in", ["class", "exception", "function"])|map(attribute="short_name")|list %}
+               {% if importable %}
+.. rubric:: Import
+
+.. code-block:: python
+
+                  {% if importable|length == 1 %}
+   from {{ import_root }}.{{ obj.name }} import {{ importable[0] }}
+                  {% else %}
+   from {{ import_root }}.{{ obj.name }} import (
+                     {% for name in importable %}
+       {{ name }},
+                     {% endfor %}
+   )
+                  {% endif %}
+
+               {% endif %}
+{{ obj.type|title }} Contents
+{{ "-" * obj.type|length }}---------
+
+               {% for obj_item in this_page_children %}
+{{ obj_item.render()|indent(0) }}
+               {% endfor %}
+            {% endif %}
+         {% endif %}
+      {% endblock %}
+   {% else %}
+.. py:module:: {{ obj.name }}
+
+      {% if obj.docstring %}
+   .. autoapi-nested-parse::
+
+      {{ obj.docstring|indent(6) }}
+
+      {% endif %}
+      {% for obj_item in visible_children %}
+   {{ obj_item.render()|indent(3) }}
+      {% endfor %}
+   {% endif %}
+{% endif %}

sphinx/conf.py

@@ -0,0 +1,147 @@
+import ast
+import os
+import sys
+
+from sphinx.ext import intersphinx
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+# -- Project info -------------------------------------------------------
+
+project = "auth0-server-python"
+author = "Auth0"
+copyright = "2024, Auth0"
+with open(os.path.join(os.path.abspath(".."), ".version")) as _version_file:
+    release = _version_file.read().strip()
+
+# -- Extensions ---------------------------------------------------------
+
+extensions = [
+    "autoapi.extension",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.linkcode",
+    "sphinx.ext.intersphinx",
+]
+
+# -- AutoAPI ------------------------------------------------------------
+
+autoapi_dirs = ["../src"]
+autoapi_type = "python"
+autoapi_root = "reference"
+autoapi_ignore = ["**/tests/**", "**/test_*.py"]
+
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+]
+autoapi_member_order = "groupwise"
+autoapi_keep_files = True
+autoapi_template_dir = "_templates/autoapi"
+autoapi_python_class_content = "class"
+
+# Top-level import package, shown in each module's import block.
+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
+    return skip
+
+
+# -- Links to other projects ---------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# -- Signatures ---------------------------------------------------------
+
+# Show `Name(...)` not `module.Name(...)`. The import block gives the full path.
+add_module_names = False
+
+# -- Source links -------------------------------------------------------
+
+REPO_ROOT = os.path.abspath("..")
+GITHUB_BLOB_URL = "https://github.com/auth0/auth0-server-python/blob/main"
+
+
+def _definition_line(path, fullname):
+    """Line where ``fullname`` (``Class.method``) is defined as a class or function, or None."""
+    with open(path) as f:
+        nodes = ast.parse(f.read()).body
+    node = None
+    for name in fullname.split("."):
+        node = next(
+            (
+                n
+                for n in nodes
+                if isinstance(n, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef))
+                and n.name == name
+            ),
+            None,
+        )
+        if node is None:
+            return None
+        nodes = node.body
+    return node.lineno if node else None
+
+
+def linkcode_resolve(domain, info):
+    if domain != "py" or not info.get("module"):
+        return None
+    base = os.path.join(REPO_ROOT, "src", IMPORT_ROOT, *info["module"].split("."))
+    path = base + ".py" if os.path.isfile(base + ".py") else os.path.join(base, "__init__.py")
+    if not os.path.isfile(path):
+        return None
+    # Attributes and fields have no definition of their own, so they get no link.
+    line = _definition_line(path, info.get("fullname", ""))
+    if line is None:
+        return None
+    return f"{GITHUB_BLOB_URL}/{os.path.relpath(path, REPO_ROOT)}#L{line}"
+
+
+# -- Napoleon (docstring style) -----------------------------------------
+
+napoleon_google_docstring = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = True
+
+# -- General ------------------------------------------------------------
+
+templates_path = ["_templates"]
+
+exclude_patterns = ["_build", "_templates", "Thumbs.db", ".DS_Store"]
+
+def _resolve_root_prefixed(app, env, node, contnode):
+    """Resolve annotations that the default lookup misses.
+
+    `auth0_server_python.x.Y` maps to AutoAPI's root-less `x.Y`, and a bare name such
+    as `Any` is looked up as `typing.Any`.
+    """
+    target = node.get("reftarget", "")
+    if node.get("refdomain") != "py":
+        return None
+    prefix = IMPORT_ROOT + "."
+    if target.startswith(prefix):
+        return env.get_domain("py").resolve_xref(
+            env, node.get("refdoc"), app.builder, node["reftype"], target[len(prefix) :], node, contnode
+        )
+    if "." not in target:
+        retargeted = node.copy()
+        retargeted["reftarget"] = "typing." + target
+        retargeted["reftype"] = "obj"
+        return intersphinx.missing_reference(app, env, retargeted, contnode)
+    return None
+
+
+def setup(app):
+    app.connect("autoapi-skip-member", autoapi_skip_member)
+    app.connect("missing-reference", _resolve_root_prefixed)

sphinx/index.rst

@@ -0,0 +1,8 @@
+auth0-server-python
+===================
+
+Auth0 server-side Python SDK: authentication flows, token management, and session handling
+for web applications.
+
+.. toctree::
+   :hidden:

sphinx/json/index.fjson

@@ -0,0 +1 @@
+{"parents": [], "prev": null, "next": {"link": "reference/", "title": "API Reference"}, "title": "auth0-server-python", "meta": null, "body": "<section id=\"auth0-server-python\">\n<h1>auth0-server-python<a class=\"headerlink\" href=\"#auth0-server-python\" title=\"Link to this heading\">\u00b6</a></h1>\n<p>Auth0 server-side Python SDK: authentication flows, token management, and session handling\nfor web applications.</p>\n<div class=\"toctree-wrapper compound\">\n</div>\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"], ["reference/index", "API Reference", "N", "next"]], "sourcename": "index.rst.txt", "toc": "<ul>\n<li><a class=\"reference internal\" href=\"#\">auth0-server-python</a></li>\n</ul>\n", "display_toc": false, "page_source_suffix": ".rst", "current_page_name": "index", "sidebars": ["about.html", "navigation.html", "relations.html", "searchbox.html", "donate.html"], "alabaster_version": "0.7.16", "alabaster_version_info": [0, 7, 16]}

sphinx/json/reference/auth_schemes/bearer_auth/index.fjson

@@ -0,0 +1 @@
+{"parents": [{"link": "../../", "title": "API Reference"}, {"link": "../", "title": "auth_schemes"}], "prev": {"link": "../", "title": "auth_schemes"}, "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<p class=\"rubric\">Import</p>\n<div class=\"highlight-python notranslate\"><div class=\"highlight\"><pre><span></span><span class=\"kn\">from</span><span class=\"w\"> </span><span class=\"nn\">auth0_server_python.auth_schemes.bearer_auth</span><span class=\"w\"> </span><span class=\"kn\">import</span> <span class=\"n\">BearerAuth</span>\n</pre></div>\n</div>\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"], ["reference/auth_schemes/client_assertion/index", "auth_schemes.client_assertion", "N", "next"], ["reference/auth_schemes/index", "auth_schemes", "P", "previous"]], "sourcename": "reference/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": "reference/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]}