MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-base
pywf-oss-base
FlaggedShared conventions, references, and scripts of the pywf-oss skills for pywf open-source Python libraries: setup, layout, code style, tests, user docs and the agent skills that hold API and maintenance knowledge, CI and hosting, release, dependencies, and secrets. Load it before ad-hoc work on modules, tests, or docs in such a repo, for a question about these conventions, or when unsure which pywf-oss skill fits a job.
references/21-readthedocs.md
View on GitHub---
description: "The uv-based build in .readthedocs.yml, the setup-readthedocs and update-github-metadata tasks, the slug and URLs, and diagnosing a failed hosted build. Read when setting up docs hosting, or when the hosted build fails or differs from the local one."
---
# Read the Docs
---
## 1. Build
- `.readthedocs.yml` installs uv, runs `uv sync --extra doc` into the Read the Docs virtualenv, and builds Sphinx from `docs/source/conf.py` (`13-sphinx.md`), with the dev Python that it reads from `mise.toml` `[tools] python` (`04-python-versions.md`).
- It builds on every push to `main`, without secrets, so notebooks ship with committed outputs (`17-nbsphinx.md`).
---
## 2. Project setup
- **Slug:** the project name with `_` replaced by `-`. The docs URL is `https://<slug>.readthedocs.io/`.
- `mise run setup-readthedocs` creates the Read the Docs project from the GitHub repo (idempotent).
- `mise run update-github-metadata` sets the GitHub repo description (from `pyproject.toml`) and homepage (the docs URL).
- Each runs only after the user's yes (`03-mise.md`).
---
## 3. Diagnosing a failed build
- **Build list and logs:** `https://app.readthedocs.org/projects/<slug>/builds/`.
- **Status from the terminal**, without printing the token:
```bash
mise exec -- sh -c 'curl -s -H "Authorization: Token $READTHEDOCS_TOKEN" "https://readthedocs.org/api/v3/projects/<slug>/builds/?limit=1"' | python3 -m json.tool
```
- **Reproduce locally** with `mise run build-doc`.
- **Fails only on Read the Docs:** a package missing from the `doc` extra is present locally through another extra (`05-uv-dependencies.md`), or the build Python differs from the local one.
- **A notebook needs credentials:** see the execution rules in `17-nbsphinx.md`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |