readthedocs-build-optimization
Read the Docs Build Optimization
Overview
Diagnose and speed up slow Read the Docs builds by reducing output formats and dependencies, choosing faster build tooling, and lowering API documentation overhead. Prefer minimal, low-risk configuration changes first.
Required inputs
- Build URL or raw logs (timing, memory errors, or timeouts).
.readthedocs.yamland documentation dependency files.- Documentation toolchain (Sphinx or MkDocs) and whether
sphinx.ext.autodocis in use. - Output formats currently enabled.
Workflow
- Confirm symptoms and scope.
- Apply low-risk optimizations first.
- Optimize the build environment when conda is involved.
- Reduce API documentation overhead if autodoc drives dependency load.
- Escalate by requesting more resources only after optimization changes.
Optimization checklist
- Reduce output formats, especially
htmlzip, before deeper changes. - Separate documentation dependencies from application dependencies.
- Prefer
mambaovercondato speed up solves and reduce memory usage. - Consider static API documentation tooling for heavy autodoc builds.
- If changes are insufficient, guide the user to request more resources.
References
- Read
references/slow-builds-troubleshooting.mdbefore making recommendations. - Docs: https://docs.readthedocs.com/platform/stable/guides/build-using-too-many-resources.html
- Docs: https://docs.readthedocs.com/platform/stable/builds.html#build-resources
- Keep suggestions aligned with the troubleshooting guide and propose the smallest change set first.
More from readthedocs/skills
readthedocs-search-api
Query the Read the Docs Search API to find documentation across projects and repositories. Use when searching documentation, finding related docs, finding API documentation, or gathering information about projects on Read the Docs.
16readthedocs-api
Full Read the Docs API v3 client guidance. Use when building or updating an API client, generating requests, or answering questions about Read the Docs API v3 endpoints (projects, versions, builds, subprojects, translations, redirects, environment variables, organizations, remote VCS resources, or embed content).
15readthedocs-write-config
Create or update Read the Docs `.readthedocs.yaml` v2 configuration files for Sphinx or MkDocs builds, including build images/tools, dependency installs, formats, custom build jobs/commands, conda environments, submodules, and search settings. Use when a user asks for a Read the Docs config file, YAML changes, or build behavior updates.
13readthedocs-redirects-manager
Manage Read the Docs redirects via the RTD API. Use when listing, creating, updating, or deleting custom redirects for a project.
12readthedocs-build-failure-triage
Triage Read the Docs build failures using build logs and config context. Use when a build fails, logs need analysis, or you need fix recommendations.
12readthedocs-project-manager
Manage Read the Docs projects via the RTD API. Use when creating projects, listing repos, triggering builds, syncing versions, or checking build status on Read the Docs.
11