Readthedocs POC

.gitignore

@@ -20,3 +20,6 @@ ts/.svelte-kit
 .yarn
 .claude/settings.local.json
 .claude/user.md
+docs/_build/
+docs/autoapi/
+/docs/_static/

.readthedocs.yaml

@@ -0,0 +1,18 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "$READTHEDOCS_VIRTUALENV_PATH"
+    install:
+      - UV_PROJECT_ENVIRONMENT="$READTHEDOCS_VIRTUALENV_PATH" uv sync --frozen --group docs

docs/api-python-modules.md

@@ -0,0 +1,9 @@
+# API Modules
+
+```{toctree}
+:maxdepth: 2
+:glob:
+
+autoapi/anki/*/index
+autoapi/anki/*/*/index
+```

docs/api-python.md

@@ -0,0 +1,9 @@
+# Python API
+
+The pages below are generated from Python docstrings in `pylib/anki`.
+
+```{toctree}
+:maxdepth: 2
+
+api-python-modules
+```

docs/api-rust.md

@@ -0,0 +1,15 @@
+# Rust API
+
+Anki's Rust API documentation is generated from doc comments in the `rslib/`
+crates using `cargo doc`.
+
+To browse the docs locally:
+
+```
+cargo doc --open
+```
+
+The main crates are:
+
+- **anki** (`rslib/`) - Core library
+- **anki_io** (`rslib/io/`) - I/O utilities

docs/conf.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+
+project = "Anki"
+copyright = "Ankitects Pty Ltd and contributors"
+author = "Ankitects Pty Ltd and contributors"
+
+ROOT = Path(__file__).resolve().parents[1]
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.intersphinx",
+    "autoapi.extension",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+myst_enable_extensions = ["colon_fence", "deflist"]
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "repository_url": "https://github.com/ankitects/anki",
+    "use_repository_button": True,
+    "use_issues_button": True,
+    "use_edit_page_button": True,
+    "path_to_docs": "docs",
+    "repository_branch": "main",
+}
+
+autoapi_type = "python"
+autoapi_dirs = [str(ROOT / "pylib" / "anki")]
+autoapi_root = "autoapi"
+autoapi_keep_files = True
+autoapi_add_toctree_entry = False
+autoapi_python_use_implicit_namespaces = True
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+]
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

docs/development.md

@@ -165,16 +165,24 @@ See [this page](./build.md)
 
 ## Generating documentation
 
-For Rust:
+To build the documentation site from `docs/`:
 
 ```
-cargo doc --open
+uv run --group docs sphinx-build -b html docs out/docs/html
+open out/docs/html/index.html
+```
+
+To build the API docs used by Anki's existing Python Sphinx pipeline:
+
+```
+./ninja python:sphinx
+open out/python/sphinx/html/py-modindex.html
 ```
 
-For Python:
+For Rust API docs:
 
 ```
-./ninja python:sphinx && open out/python/sphinx/html/py-modindex.html
+cargo doc --open
 ```
 
 ## Environmental Variables

docs/index.md

@@ -0,0 +1,23 @@
+# Anki Documentation
+
+## Prose
+
+```{toctree}
+:maxdepth: 2
+
+readme
+development
+build
+contributing
+architecture
+protobuf
+```
+
+## API
+
+```{toctree}
+:maxdepth: 2
+
+api-python
+api-rust
+```

docs/readme.md

@@ -0,0 +1,4 @@
+# Project README
+
+```{include} ../README.md
+```

pyproject.toml

@@ -25,11 +25,10 @@ dev = [
   "types-waitress",
   "types-pywin32",
 ]
-
-[project.optional-dependencies]
-sphinx = [
+docs = [
   "sphinx",
-  "sphinx_rtd_theme",
+  "myst-parser",
+  "sphinx-book-theme",
   "sphinx-autoapi",
 ]
 

rslib/Cargo.toml

@@ -96,7 +96,7 @@ sha1.workspace = true
 snafu.workspace = true
 strum.workspace = true
 tempfile.workspace = true
-tokio.workspace = true
+tokio = { workspace = true, features = ["io-util"] }
 tokio-util.workspace = true
 tower-http.workspace = true
 tracing.workspace = true