readthedocs-project-manager_skill

Overview

This skill manages Read the Docs projects through the Read the Docs API, covering project creation, repository listing, version syncs, and build operations. It streamlines the core lifecycle tasks needed to provision and verify documentation sites on either the community or business RTD host. Use it to automate project setup and monitor build status without manual API calls.

How this skill works

The skill talks to the RTD API at the configured RTD_HOST and authenticates with an API token supplied via RTD_TOKEN or provided at runtime. It can list remote repositories, create projects with minimal required fields, sync versions for a project, trigger builds for a specified version, and poll the latest build status. All requests use standard REST endpoints under /api/v3/ and include Authorization: Token <token> headers.

When to use it

• Creating a new Read the Docs project from a repository URL and slug.
• Verifying repository access or selecting a repo from RTD integrations.
• Triggering a build after pushing documentation changes or updating versions.
• Syncing versions to discover new branches or tags for a project.
• Checking the latest build status for troubleshooting or CI gating.

Best practices

• Set RTD_HOST to the correct host: app.readthedocs.org for community or app.readthedocs.com for business.
• Keep API tokens secret; never log or print RTD_TOKEN in outputs.
• Confirm the project slug is available and the repository URL is reachable before creating a project.
• Use sync-versions after onboarding a repo to ensure branches and tags appear as versions.
• Poll builds with a reasonable interval and timeout to avoid rate limits or unnecessary API load.

Example use cases

• Automate onboarding: create a project, sync versions, and trigger an initial build in a single workflow.
• CI integration: trigger a docs build for the latest commit and poll build status to pass/fail a pipeline step.
• Repository verification: list remote repositories to confirm integration permissions before creating a project.
• Troubleshooting: fetch the latest build metadata to inspect logs and failure reasons after a broken build.