sphinx-ask-chatgpt

The initial release version is 0.0.1.

An extension for Sphinx HTML and dirhtml builds, requiring Python 3.11 or later and Sphinx 7.4 or later, below 10.

pip install ./sphinx-ask-chatgpt

Register it in conf.py:

extensions = ["sphinx_ask_chatgpt"]
# Optional settings; both default to True.
ask_chatgpt_enabled = True
ask_chatgpt_adjust_layout = True

The extension inserts the widget only into regular document pages. It does not insert it into generated search/index pages, non-HTML builds, or singlehtml builds. No template override is required. Disabling the extension empties the document manifest and removes old references. Layout adjustment applies only to Alabaster and does not impose that layout on other themes. Reference retrieval is independent of the theme.

Local serving

The serve extra adds fastapi-chatgpt-plan==0.1.0 and Uvicorn. Backend 0.1.0 is fetched from PyPI; the original repository checkout is not required.

pip install './sphinx-ask-chatgpt[serve]'
sphinx-build -W -b html docs docs/_build/html
CHATGPT_PLAN_ENABLED=true sphinx-ask-chatgpt serve --html docs/_build/html

Open http://127.0.0.1:8000/. Set CHATGPT_APP_PORT to change the port and CHATGPT_STATE_DIR to change the registration directory. You can reuse the existing backend registration directory. OAuth tokens, browser sessions, and authentication return targets are held only in memory. Building documentation requires no npm, Node.js, running server, or authentication. Importing the extension does not import FastAPI.

Generated references

At doctree-resolved, the extension extracts headings, paragraphs, lists, tables, code examples, and autodoc signatures and descriptions from the expanded, resolved document tree. This includes nested and partial includes, literalinclude, substitutions, and HTML-only conditional content. Comments, build warnings, and the bodies of other pages referenced by a table of contents are excluded. Code line breaks and indentation are preserved. The extension works with html_copy_source=False and hidden source links.

It generates _ask_chatgpt/documents/<SHA-256 of docname>.json and _ask_chatgpt/manifest.json. The manifest records output URLs supplied by the builder, and the bootstrap passes the docname registered at build time. GET /_chatgpt/document?doc=<docname> retrieves only registered references; arbitrary file paths and external URLs are not accepted. At runtime, only the generated HTML and references are needed. Source files and pickled doctrees are not read.

In this initial version, incremental builds reread all current documents to reliably reflect include and docstring changes. Deleting a document removes its manifest entry and reference. Build-time optimization is future work. The extension does not declare parallel-build safety, and parallel builds are outside the supported scope.

Server and OAuth compatibility

Document routes are composed into the same FastAPI application created by the backend factory, preserving Host, Origin, CSRF, and cookie renewal behavior. /api, /auth, /health, /_chatgpt, and /_ask_chatgpt are reserved. Unknown API routes do not fall back to document files. Document, reference, and asset serving reject path traversal and symlinks resolving outside the selected directories.

Authentication return targets must identify existing same-origin HTML documents. They are bound to the OAuth state, original browser session, generation, and expiration. The adapter delegates to the original login/callback functions and changes the return target only after successful validation and cookie rotation. This internal compatibility dependency is confined to auth_return.py, and the backend dependency is pinned to 0.1.0. Future backend upgrades require compatibility tests and an updated dependency constraint.

This is a local, single-account, single-process implementation. The widget can appear on public sites, but HTTPS deployment, per-visitor session/token isolation, and cloud authentication are outside the current scope. Real-account verification is recorded in the root implementation-report.md.

Distribution and API references

The canonical shared JavaScript lives in ../ask-ai/src/ and is bundled using ../tools/sync-widget-assets.py. Its version and SHA-256 hashes are recorded in widget-version.json and checked for consistency in CI. A wheel can be built from the sdist alone, so installing the package does not require the sibling JavaScript directory.

• Sphinx Application API
• Sphinx document events