Skip to content

docs: Added basic sphinx generation setup - #150

Open
rmad17 wants to merge 8 commits into
mainfrom
docs/mintlify-poc
Open

rmad17 wants to merge 8 commits into
mainfrom
docs/mintlify-poc

Conversation

@rmad17

@rmad17 rmad17 commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds an optional Sphinx build that generates the SDK's API reference from its docstrings, so Mintlify can publish it. The build uses sphinx-autoapi and napoleon with Sphinx's default theme and no custom extensions or templates. It outputs one JSON page per public module, and the committed copy in sphinx/json/ is what Mintlify consumes. The docs dependencies live in an optional Poetry group, so installing and testing the SDK works as before. The PR adds no runtime behavior and changes no SDK code.

Changes

  • sphinx/conf.py, sphinx/index.rst: minimal Sphinx config using sphinx-autoapi to generate one page per module under a toctree, with napoleon for the docstrings. autoapi_options omits imported-members so the package's re-exports aren't documented twice. release is read from .version.
  • sphinx/Makefile: help, html, json and clean targets. make -C sphinx json is equivalent to the sphinx-build -b json command below and writes to sphinx/json.
  • pyproject.toml, poetry.lock: new optional Poetry docs group with sphinx 8.1.3 and sphinx-autoapi (>=3.4,<4), all python >=3.10. The group is optional, so poetry install and the existing CI test workflow are unchanged.
  • .gitignore: ignores sphinx/_build/ (build output) and sphinx/autoapi/ (intermediate files sphinx-autoapi writes during a build). It also ignores everything in sphinx/json/ except autoapi/ and index.fjson, so only the page JSON is committed and the rest of the Sphinx output (_sources, _static, searchindex.json, objects.inv and so on) stays untracked.
  • sphinx/json/: 14 generated .fjson files (about 316 KB), built with sphinx-build -b json directly into this directory. They are committed so Mintlify can consume them without a build step. Nothing regenerates them yet, so they will go stale after the next API change.

Build commands:

poetry install --with docs
poetry run sphinx-build -b html sphinx sphinx/_build/html
poetry run sphinx-build -b json sphinx sphinx/json

@rmad17
rmad17 requested a review from a team as a code owner October 26, 2026 13:14
Comment thread sphinx/conf.py

project = "auth0-api-python"
with open(os.path.join(os.path.abspath(".."), ".version")) as _version_file:
release = _version_file.read().strip()

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants