AgentSkillsCN

readthedocs-build-failure-triage

利用构建日志与配置上下文，对Read the Docs的构建失败进行分类与诊断。适用于构建失败、日志需要分析，或需要故障修复建议时使用。

SKILL.md
--- frontmatter
name: readthedocs-build-failure-triage
description: 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.

Read the Docs Build Failure Triage

Use RTD build metadata plus raw build logs to identify the failure category and recommend fixes. This is a diagnostic workflow, not just API wrapping.

Required inputs

  • •RTD host in RTD_HOST
    • •Community: https://app.readthedocs.org
    • •Business: https://app.readthedocs.com
  • •API token available in RTD_TOKEN (preferred) or provided by the user
  • •Project slug
  • •Build logs (raw text) or a build URL the user can open

Quick workflow

  1. •Fetch the latest build metadata.
  2. •Open the build page and view raw logs.
  3. •Identify the failure category and apply fixes.
  4. •If warnings are hidden, enable sphinx.fail_on_warning to make them visible.

Get build metadata

Latest build:

bash
curl -s -H "Authorization: Token $RTD_TOKEN" \
  "${RTD_HOST}/api/v3/projects/project-slug/builds/?limit=1"

Specific build:

bash
curl -s -H "Authorization: Token $RTD_TOKEN" \
  "${RTD_HOST}/api/v3/projects/project-slug/builds/123456/"

Use the urls.build value from the API to open the build page. From there, use the "View raw" link to copy the full log.

Get the raw log directly

Read the Docs exposes raw build logs via the API v2 text endpoint:

code
GET ${RTD_HOST}/api/v2/build/{build_id}.txt

Example:

bash
curl -s -H "Authorization: Token $RTD_TOKEN" \
  "${RTD_HOST}/api/v2/build/123456.txt"

Common failure categories and fixes

Dependency install failures

Symptoms: pip install errors, missing packages, resolver conflicts.

Actions:

  • •Verify python.install requirements path in .readthedocs.yaml.
  • •Pin versions for brittle deps and add missing build tools.
  • •For Sphinx autodoc failures, install the project with python.install:
    • •method: pip
    • •path: .

Missing config file or wrong path

Symptoms: conf.py not found, mkdocs.yml not found.

Actions:

  • •Check sphinx.configuration or mkdocs.configuration paths.
  • •Confirm repo layout matches configured paths.

Build tool mismatch

Symptoms: Sphinx config but MkDocs project (or vice versa).

Actions:

  • •Confirm .readthedocs.yaml uses the right tool block.
  • •Ensure dependencies align with the tool (Sphinx vs MkDocs).

Warnings treated as failures

Symptoms: build fails after enabling warnings-as-errors.

Actions:

  • •Fix the warning in logs, or temporarily disable sphinx.fail_on_warning.
  • •Use warnings to prioritize broken references/imports.

Resource limits or timeouts

Symptoms: build timeouts, memory errors, OOM kills.

Actions:

  • •Reduce build scope or switch to incremental tooling.
  • •Split large docs builds or trim heavy extensions.
  • •For Business, request more resources if needed.

Version-specific failures

Symptoms: only a tag/branch fails.

Actions:

  • •Check version-specific dependencies or config drift.
  • •Verify default_branch and version slugs.
  • •If a version is obsolete, consider hiding it.

Notes from RTD docs

  • •Use build logs to make warnings visible and fix underlying issues.
  • •Read the Docs can disable builds after too many consecutive failures.
  • •Build notifications (email/webhooks) help catch failures quickly.