Skip to content

Add Sphinx documentation for Read the Docs - #17

Merged
bpepple merged 1 commit into
mainfrom
docs
Nov 3, 2026
Merged

bpepple merged 1 commit into
mainfrom
docs

Conversation

@bpepple

@bpepple bpepple commented Nov 3, 2026

Copy link
Copy Markdown
Member

Summary

The README had grown into the full guide. This moves the guide into Sphinx documentation for Read the Docs, at https://izaya.readthedocs.io/, and shortens the README to a quick start that links to it.

  • docs/: Sphinx pages written in Markdown with MyST, using the Furo theme. Installation, usage, private data, styling and JavaScript are moved from the README with their wording unchanged. There are also pages for the example project, development and the changelog, which includes CHANGELOG.md.
  • docs/api.md: an API reference generated from the docstrings for register, Lookup, ModelLookup, Item and LookupWidget. It also covers the IZAYA_CLASSES and IZAYA_LOGIN_REQUIRED settings and the izaya.E001 and izaya.W001 system checks.
  • .readthedocs.yaml: installs the new docs dependency group with uv on Python 3.14, and fails the build on any warning.
  • testing.yml: a new Docs job builds the documentation with sphinx-build -W, so a change that breaks the docs fails CI.
  • LookupWidget's docstring now explains lookup, multiple and classes, including that classes replaces the IZAYA_CLASSES value for each key it sets.
  • pyproject.toml adds a Documentation project URL.

To build the documentation locally:

uv run --group docs sphinx-build -W docs docs/_build/html

Move the guide out of the README into Sphinx pages written in Markdown
with MyST, using the Furo theme, and add an API reference generated from
the docstrings. .readthedocs.yaml installs the new docs dependency group
with uv and fails the build on warnings, and a CI job builds the docs
the same way.

The README is now a quick start that links to the documentation.
LookupWidget's docstring explains its arguments.
@bpepple bpepple self-assigned this Nov 3, 2026
@bpepple bpepple added documentation Improvements or additions to documentation patch labels Nov 3, 2026
@bpepple
bpepple merged commit 9fc13ea into main Nov 3, 2026
10 checks passed
@bpepple
bpepple deleted the docs branch November 3, 2026 16:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation patch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant