Skip to content

docs: Added basic sphinx generation setup - #150

Merged
rmad17 merged 11 commits into
mainfrom
docs/mintlify-poc
Nov 13, 2026
Merged

rmad17 merged 11 commits into
mainfrom
docs/mintlify-poc

Conversation

@rmad17

@rmad17 rmad17 commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Changes

Adds an optional Sphinx build that generates the SDK's API reference from its docstrings as JSON. It uses sphinx-autoapi and napoleon with Sphinx's default theme, with no custom extensions, templates or hooks. The generated pages are committed under sphinx/json/. The PR adds no runtime behavior and changes no SDK code.

  • sphinx/conf.py, sphinx/index.rst: AutoAPI config with autoapi_root = ".", so pages are written to sphinx/json/auth0_api_python/<module>/index.fjson. release is read from .version. The package page auth0_api_python/index.rst is excluded, because it only lists the submodules and repeats the package docstring. autoapi_options omits imported-members, so re-exports aren't documented twice. index.rst has a hidden glob toctree.
  • sphinx/Makefile: help, html, json and clean targets. Paths are anchored to the Makefile's location, so it works from any directory. make -f sphinx/Makefile json is equivalent to the sphinx-build -b json command below.
  • pyproject.toml, poetry.lock: new optional Poetry docs group with sphinx 8.1.3 and sphinx-autoapi (>=3.4,<4), both python >=3.10. The group is optional, so poetry install and the existing CI test workflow are unchanged.
  • .gitignore: ignores sphinx/_build/, the module sources AutoAPI writes next to conf.py (sphinx/*/), and the non-page files Sphinx writes into sphinx/json/ (_sources, _static, searchindex.json, genindex.fjson and so on). Only the page JSON is tracked.
  • sphinx/json/: 12 generated .fjson files, 11 module pages and the root index.fjson. Nothing regenerates them automatically, so they must be rebuilt and committed when the public API or docstrings 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

Testing

No unit or integration tests apply, because the PR adds no runtime code. To check the output, run the build commands above and confirm git status sphinx/json shows no changes. The generated JSON has not been tested against a documentation site.

  • This change adds unit test coverage
  • This change adds integration test coverage
  • This change has been tested on the latest version of the platform/language or why not

Checklist

@rmad17
rmad17 requested a review from a team as a code owner October 26, 2026 13:14
Comment thread sphinx/conf.py Fixed
cschetan77
cschetan77 previously approved these changes Nov 5, 2026
cschetan77
cschetan77 previously approved these changes Nov 12, 2026
@rmad17
rmad17 merged commit 8486926 into main Nov 13, 2026
8 checks passed
@rmad17
rmad17 deleted the docs/mintlify-poc branch November 13, 2026 17:04
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.

4 participants