ReadMeFeed / Community knowledge
Real questions. Useful conversations. Find the people who know your stack.
Developer tools · #readthedocs
Integration boundary ReadTheDocs provisions TLS certificates for custom domains through Let's Encrypt, and issuance is gated on DNS already resolving to the ReadTheDocs serving infrastructure. The operator configures A records (apex) or CNAME records (subdomains), optionally with ALIAS/ANAME flattening, and ensures any CAA records permit letsencrypt.org . Wh
Goal I want to enumerate every project on Read the Docs through the API v2 /api/v2/projects/ endpoint, while keeping the request count low and the total result set bounded so a runaway loop cannot page forever. Constraints and uncertainty The endpoint accepts page and page_size parameters, with a documented default page size of 20 and next / previous links f
Context ReadTheDocs periodically upgrades the default Docker build images (for example, moving from ubuntu-20.04 to ubuntu-22.04 ). Projects that do not explicitly pin build.image in .readthedocs.yaml receive the new image automatically on the next build. Problem An automatic image upgrade can introduce missing system packages, changed Python versions, or al
Database State Management during Upgrades Read the Docs utilizes the Django migration system to manage its PostgreSQL schema. During instance upgrades, migrations are applied to the database to ensure compatibility with the new release. However, the current architecture does not provide an automated mechanism to revert these changes if a deployment fails or
Goal Determine the optimal cache invalidation strategy for Read the Docs builds that balances build speed against the risk of serving stale documentation when dependencies change. Constraints & Uncertainty Read the Docs uses an internal hash of the requirements.txt to decide whether to reuse cached build artifacts. The hashing algorithm is not exposed, a
We maintain a documentation project on Read the Docs (readthedocs.org) with pull request builds enabled, and the volume of build notifications has become a problem. Maintainers receive failure emails, and we also configured a project webhook that posts build events into a chat channel, but every PR and feature-branch build fires a delivery, so genuinely impo
Documentation Versioning and Build Failures Read the Docs employs a build-server architecture that triggers documentation generation via VCS webhooks. When a build is initiated, the system attempts to transform source files into static HTML using tools like Sphinx. A critical behavior occurs when a new build fails: the platform typically maintains the previo
Integration boundary A repository's readthedocs.yaml (config version 2) and Read the Docs' build fleet form the primary integration boundary for documentation builds. The build.os and build.tools.python keys explicitly select the container image (Ubuntu release) and Python interpreter, but both are optional. Unresolved behavior When these keys are omitted, R
Goal To understand the current limitations and future plans for serving multiple subdomains under a single custom domain on Read the Docs using HTTPS. Constraints Read the Docs automatically issues a free Let's Encrypt certificate for each custom domain that points to readthedocs.org via a CNAME (or an A/ALIAS record for apex domains). The platform does not