Read the Docs

https://docs.readthedocs.com/platform/stable
Admin
Read the Docs simplifies managing software documentation by building and hosting your docs...
Tokens:118,864
Snippets:1,670
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies with pixi

Source: https://docs.readthedocs.com/platform/stable/build-customization.html

Use pixi for dependency management, potentially reducing installation time. This example installs from a 'docs' environment and runs Sphinx.

```yaml
version: 2

build:
   os: ubuntu-24.04
   tools:
       python: "latest"
   jobs:
      create_environment:
         - asdf plugin add pixi
         - asdf install pixi latest
         - asdf global pixi latest
      install:
         # assuming you have an environment called "docs"
         - pixi install -e docs
      build:
         html:
            - pixi run -e docs sphinx-build -T -b html docs $READTHEDOCS_OUTPUT/html


```

--------------------------------

### Python Environment Setup with Requirements File

Source: https://docs.readthedocs.com/platform/stable/config-file/v2.html

Installs Python dependencies from a specified requirements file.

```yaml
version: 2

python:
  install:
    - requirements: docs/requirements.txt
    - method: pip
      path: .
      extra_requirements:
        - docs
    - method: pip
      path: another/package

```

--------------------------------

### Build with Pelican

Source: https://docs.readthedocs.com/platform/stable/build-customization.html

Configure your build to use Pelican, a static site generator. This example installs Pelican with markdown support and then builds the HTML output.

```yaml
version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  jobs:
    install:
      - pip install pelican[markdown]
    build:
      html:
        - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/


```

--------------------------------

### Install Node.js Dependencies

Source: https://docs.readthedocs.com/platform/stable/build-customization.html

Install Node.js and npm dependencies as part of the build process. This example installs dependencies from package.json and globally installs jsdoc.

```yaml
version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.9"
    nodejs: "16"
  jobs:
    post_install:
      # Install dependencies defined in your ``package.json``
      - npm ci
      # Install any other extra dependencies to build the docs
      - npm install -g jsdoc

```

--------------------------------

### Build with Asciidoctor

Source: https://docs.readthedocs.com/platform/stable/build-customization.html

Configure your build to use Asciidoctor for converting AsciiDoc source to HTML. This example installs Asciidoctor globally and then runs the build command.

```yaml
version: 2
build:
  os: "ubuntu-22.04"
  tools:
    nodejs: "20"
  jobs:
    install:
      - npm install -g asciidoctor
    build:
      html:
        - asciidoctor -D $READTHEDOCS_OUTPUT/html index.asciidoc


```

--------------------------------

### Install from Multiple Requirements Files

Source: https://docs.readthedocs.com/platform/stable/config-file/v2.html

Installs Python packages by specifying multiple requirements files.

```yaml
version: 2

python:
  install:
    - requirements: docs/requirements.txt
    - requirements: requirements.txt

```

--------------------------------

### Install sphinx-intl

Source: https://docs.readthedocs.com/platform/stable/guides/manage-translations-sphinx.html

Install the sphinx-intl tool using pip. This is the first step for manual translation workflows.

```bash
pip install sphinx-intl

```

--------------------------------

### Project Active Versions Response Example

Source: https://docs.readthedocs.com/platform/stable/api/v2.html

Example JSON response structure for retrieving active versions of a project.

```json
{
    "versions": [VERSION, VERSION, ...]
}

```

--------------------------------

### Build Warnings Example

Source: https://docs.readthedocs.com/platform/stable/tutorial/index.html

Example of build warnings that may occur during the documentation process, indicating issues like failed imports.

```text
WARNING: [autosummary] failed to import 'lumache': no module named lumache
...
WARNING: autodoc: failed to import function 'get_random_ingredients' from module 'lumache'; the following exception was raised:
No module named 'lumache'
WARNING: autodoc: failed to import exception 'InvalidKindError' from module 'lumache'; the following exception was raised:
No module named 'lumache'


```

--------------------------------

### Intersphinx Example for Read the Docs

Source: https://docs.readthedocs.com/platform/stable/guides/cross-referencing-with-sphinx.html

An example of using the sphinx.ext.intersphinx module to list targets from the Read the Docs documentation site.

```python
python -m sphinx.ext.intersphinx https://docs.readthedocs.io/en/stable/objects.inv
```

--------------------------------

### Example File Path

Source: https://docs.readthedocs.com/platform/stable/tutorial/index.html

This is the path to the index.rst file within the documentation source.

```text
docs/source/index.rst
```

--------------------------------

### APT Packages Installation

Source: https://docs.readthedocs.com/platform/stable/config-file/v2.html

Lists APT packages to be installed during the build process. This is useful for system-level dependencies required by the project.

```yaml
version: 2

build:
  apt_packages:
    - libclang
    - cmake

```

--------------------------------

### Project List Response Example

Source: https://docs.readthedocs.com/platform/stable/api/v2.html

Example JSON response structure for a project list request.

```json
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [PROJECTS]
}

```

--------------------------------

### Example Response for Listing Projects

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

This is an example JSON response when successfully retrieving a list of projects from an organization. It includes details about the projects found and pagination information.

```json
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "_links": {
                "_self": "https://app.readthedocs.com/api/v3/projects/pypa-pip/",
                "builds": "https://app.readthedocs.com/api/v3/projects/pypa-pip/builds/",
                "environmentvariables": "https://app.readthedocs.com/api/v3/projects/pypa-pip/environmentvariables/",
                "redirects": "https://app.readthedocs.com/api/v3/projects/pypa-pip/redirects/",
                "subprojects": "https://app.readthedocs.com/api/v3/projects/pypa-pip/subprojects/",
                "superproject": "https://app.readthedocs.com/api/v3/projects/pypa-pip/superproject/",
                "translations": "https://app.readthedocs.com/api/v3/projects/pypa-pip/translations/",
                "versions": "https://app.readthedocs.com/api/v3/projects/pypa-pip/versions/"
            },
            "created": "2019-02-22T21:59:13.333614Z",
            "default_branch": "master",
            "default_version": "latest",
            "homepage": null,
            "id": 2797,
            "language": {
                "code": "en",
                "name": "English"
            },
            "modified": "2019-08-08T16:27:25.939531Z",
            "name": "pip",
            "programming_language": {
                "code": "py",
                "name": "Python"
            },
            "repository": {
                "type": "git",
                "url": "https://github.com/pypa/pip"
            },
            "slug": "pypa-pip",
            "subproject_of": null,
            "tags": [],
            "translation_of": null,
            "urls": {
                "builds": "https://app.readthedocs.com/projects/pypa-pip/builds/",
                "documentation": "https://pypa-pip.readthedocs-hosted.com/en/latest/",
                "home": "https://app.readthedocs.com/projects/pypa-pip/",
                "versions": "https://app.readthedocs.com/projects/pypa-pip/versions/"
            }
        }
    ]
}

```

--------------------------------

### Install using uv pip with Path and Extras

Source: https://docs.readthedocs.com/platform/stable/config-file/v2.html

Installs Python dependencies using uv pip from a local path and includes specified optional extras.

```yaml
version: 2

python:
   install:
      - method: uv
        command: pip
        path: .
        extras:
           - docs

```

--------------------------------

### Install using uv sync with Groups

Source: https://docs.readthedocs.com/platform/stable/config-file/v2.html

Installs Python dependencies using uv sync, specifying dependency groups from pyproject.toml.

```yaml
version: 2

python:
   install:
      - method: uv
        command: sync
        groups:
           - docs

```

--------------------------------

### Install Dependencies with Poetry

Source: https://docs.readthedocs.com/platform/stable/build-customization.html

Use the `post_create_environment` job to install Python dependencies with Poetry. Ensure `VIRTUAL_ENV` is set manually.

```yaml
version: 2

build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  jobs:
    post_install:
      # Install poetry
      # https://python-poetry.org/docs/#installing-manually
      - pip install poetry
      # Install dependencies with 'docs' dependency group
      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
      # VIRTUAL_ENV needs to be set manually for now.
      # See https://github.com/readthedocs/readthedocs.org/pull/11152/
      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs

sphinx:
  configuration: docs/conf.py


```

--------------------------------

### Install Read the Docs Skills using Agent Skills CLI

Source: https://docs.readthedocs.com/platform/stable/reference/agent-skills.html

If your agent supports the Agent Skills CLI, use this command to install the Read the Docs skills repository. This simplifies the integration process.

```bash
npx skills add readthedocs/skills

```

--------------------------------

### Example Addons Data Structure

Source: https://docs.readthedocs.com/platform/stable/addons.html

This is an example of the data structure available through the 'readthedocs-addons-data-ready' event. It includes details about addons, builds, projects, and versions.

```json
{
"addons": {
    "Most of this config is currently for internal use.": "We are working on making this more public."
},
"api_version": "1",
"builds": {
    "current": {
        "commit": "6db46a36ed3da98de658b50c66b458bbfa513a4e",
        "created": "2025-01-07T16:02:16.842871Z",
        "duration": 78,
        "error": "",
        "finished": "2025-01-07T16:03:34.842Z",
        "id": 26773762,
        "project": "docs",
        "state": {
            "code": "finished",
            "name": "Finished"
        },
        "success": true,
        "urls": {
            "build": "https://app.readthedocs.org/projects/docs/builds/26773762/",
            "project": "https://app.readthedocs.org/projects/docs/",
            "version": "https://app.readthedocs.org/projects/docs/version/stable/edit/"
        },
        "version": "stable"
    }
},
"domains": {
    "dashboard": "readthedocs.org"
},
"projects": {
    "current": {
        "created": "2016-12-20T06:26:09.098922Z",
        "default_branch": "main",
        "default_version": "stable",
        "external_builds_privacy_level": "public",
        "homepage": null,
        "id": 74581,
        "language": {
            "code": "en",
            "name": "English"
        },
        "modified": "2024-11-13T17:09:09.007795Z",
        "name": "docs",
        "privacy_level": "public",
        "programming_language": {
            "code": "py",
            "name": "Python"
        },
        "repository": {
            "type": "git",
            "url": "https://github.com/readthedocs/readthedocs.org"
        },
        "single_version": false,
        "slug": "docs",
        "subproject_of": null,
        "tags": [
            "docs",
            "python",
            "sphinx-doc"
        ],
        "translation_of": null,
        "urls": {

```

--------------------------------

### Install Transifex CLI

Source: https://docs.readthedocs.com/platform/stable/guides/manage-translations-sphinx.html

Install the Transifex Command Line Interface (CLI) tool using a provided script. This tool is essential for interacting with the Transifex platform.

```bash
curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

```

--------------------------------

### Install using uv pip with Requirements File

Source: https://docs.readthedocs.com/platform/stable/config-file/v2.html

Installs Python dependencies using uv pip, pointing to a specific requirements file.

```yaml
version: 2

python:
   install:
      - method: uv
        command: pip
        requirements: docs/requirements.txt

```

--------------------------------

### Example Project Response

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

This is an example JSON response when retrieving a list of projects. It includes details like project ID, name, slugs, creation/modification dates, language, repository information, and links to related API endpoints.

```json
{
    "count": 25,
    "next": "/api/v3/projects/?limit=10&offset=10",
    "previous": null,
    "results": [{
        "id": 12345,
        "name": "Pip",
        "slug": "pip",
        "created": "2010-10-23T18:12:31+00:00",
        "modified": "2018-12-11T07:21:11+00:00",
        "language": {
            "code": "en",
            "name": "English"
        },
        "programming_language": {
            "code": "py",
            "name": "Python"
        },
        "repository": {
            "url": "https://github.com/pypa/pip",
            "type": "git"
        },
        "default_version": "stable",
        "default_branch": "master",
        "subproject_of": null,
        "translation_of": null,
        "urls": {
            "documentation": "http://pip.pypa.io/en/stable/",
            "home": "https://pip.pypa.io/"
        },
        "tags": [
            "distutils",
            "easy_install",
            "egg",
            "setuptools",
            "virtualenv"
        ],
        "users": [
            {
                "username": "dstufft"
            }
        ],
        "active_versions": {
            "stable": "{VERSION}",
            "latest": "{VERSION}",
            "19.0.2": "{VERSION}"
        },
        "_links": {
            "_self": "/api/v3/projects/pip/",
            "versions": "/api/v3/projects/pip/versions/",
            "builds": "/api/v3/projects/pip/builds/",
            "subprojects": "/api/v3/projects/pip/subprojects/",
            "superproject": "/api/v3/projects/pip/superproject/",
            "redirects": "/api/v3/projects/pip/redirects/",
            "translations": "/api/v3/projects/pip/translations/"
        }
    }]
}

```

--------------------------------

### Private GitLab Package Installation URI

Source: https://docs.readthedocs.com/platform/stable/guides/private-python-packages.html

This URI format is for installing private packages from GitLab using a deploy token. Replace placeholders with your deploy token user, token, and version. Environment variables are recommended for security.

```bash
git+https://${GITLAB_TOKEN_USER}:${GITLAB_TOKEN}@gitlab.com/user/project.git@{version}
```

--------------------------------

### Python Dependency Pinning Examples

Source: https://docs.readthedocs.com/platform/stable/glossary.html

Examples of how to pin Python dependencies for reproducible builds. Exact pinning is recommended to avoid incompatibilities from new package releases.

```python
# Exact pinning: Only allow Sphinx 5.3.0
sphinx==5.3.0
```

```python
# Loose pinning: Lower and upper bounds result in the latest 5.3.x release
sphinx>=5.3,<5.4
```

```python
# Very loose pinning: Lower and upper bounds result in the latest 5.x release
sphinx>=5,<6
```

--------------------------------

### Build with Docsify

Source: https://docs.readthedocs.com/platform/stable/build-customization.html

Configure your build for Docsify, which generates documentation websites on the fly. This example creates the output directory and copies documentation files.

```yaml
version: 2
build:
  os: "ubuntu-22.04"
  jobs:
    build:
      html:
        - mkdir --parents $READTHEDOCS_OUTPUT/html/
        - cp --recursive docs/* $READTHEDOCS_OUTPUT/html/


```

--------------------------------

### Enable PDF and ePub Formats

Source: https://docs.readthedocs.com/platform/stable/guides/enable-offline-formats.html

Configure the 'formats' key in your configuration file to specify which offline formats to build. This example enables both EPUB and PDF.

```yaml
# Build PDF & ePub
formats:
  - epub
  - pdf

```

--------------------------------

### GET /api/v3/embed/

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

Retrieves HTML-formatted content from a documentation page or section. It's recommended to read the 'How to embed content from your documentation' guide for detailed usage instructions. Be cautious as content is returned as-is without sanitization.

```APIDOC
## GET /api/v3/embed/

### Description
Retrieve HTML-formatted content from documentation page or section. Read How to embed content from your documentation to know more about how to use this endpoint.

Warning
The content will be returned as is, without any sanitization or escaping. You should not include content from arbitrary projects, or projects you do not trust.

### Method
GET

### Endpoint
/api/v3/embed/

### Parameters
#### Query Parameters
- **url** (string) - Required - Full URL of the document (with optional fragment) to fetch content from.
- **doctool** (string) - Optional - Documentation tool key name used to generate the target documentation (currently, only `sphinx` is accepted).
- **doctoolversion** (string) - Optional - Documentation tool version used to generate the target documentation (e.g. `4.2.0`).
- **maincontent** (string) - Optional - CSS selector for the main content of the page (e.g. `div#main`).

Note
Passing `?doctool=`, `?doctoolversion=` and `?maincontent=` may improve the response since the endpoint will know more about the exact structure of the HTML and can make better decisions.

### Request Example
```
curl https://app.readthedocs.org/api/v3/embed/?url=https://docs.readthedocs.com/platform/stable/reference/features.html%23feature-reference
```

### Response
#### Success Response (200)
- **url** (string) - URL of the document.
- **fragment** (string) - fragmet part of the URL used to query the page.
- **content** (string) - HTML content of the section.
- **external** (string) - whether or not the page is hosted on Read the Docs or externally.

#### Response Example
```json
{
    "url": "https://docs.readthedocs.com/platform/stable/reference/features.html#feature-reference",
    "fragment": "feature-reference",
    "content": "<section id=\"feature-reference\">\n<h1>Feature reference ...",
    "external": false
}
```
```

--------------------------------

### Example Response for Project Details

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

This is a sample JSON response when retrieving project details. It includes various attributes of the project.

```json
{
    "id": 12345,
    "name": "Pip",
    "slug": "pip",
    "created": "2010-10-23T18:12:31+00:00",
    "modified": "2018-12-11T07:21:11+00:00",
    "language": {
        "code": "en",
        "name": "English"
    },
    "programming_language": {
        "code": "py",
        "name": "Python"
    },
    "repository": {
        "url": "https://github.com/pypa/pip",
        "type": "git"
    },
    "default_version": "stable",
    "default_branch": "master",
    "subproject_of": null,
    "translation_of": null,
    "urls": {
        "documentation": "http://pip.pypa.io/en/stable/",
        "home": "https://app.readthedocs.org/projects/pip/",
        "downloads": null,
        "builds": "https://app.readthedocs.org/projects/pip/builds/",
        "versions": "https://app.readthedocs.org/projects/pip/versions/",
    },
    "tags": [
        "distutils",
        "easy_install",
        "egg",
        "setuptools",
        "virtualenv"
    ],
    "users": [
        {
            "username": "dstufft"
        }
    ],
    "active_versions": {
        "stable": "{VERSION}",
        "latest": "{VERSION}",
        "19.0.2": "{VERSION}"
    },
    "privacy_level": "public",
    "external_builds_privacy_level": "public",
    "versioning_scheme": "multiple_versions_with_translations",
    "readthedocs_yaml_path": null,
    "_links": {
        "_self": "/api/v3/projects/pip/",
        "versions": "/api/v3/projects/pip/versions/",
        "builds": "/api/v3/projects/pip/builds/",
        "subprojects": "/api/v3/projects/pip/subprojects/",
        "superproject": "/api/v3/projects/pip/superproject/",
        "redirects": "/api/v3/projects/pip/redirects/",
        "translations": "/api/v3/projects/pip/translations/"
    }
}
```

--------------------------------

### Install Dependencies from Dependency Groups with pip

Source: https://docs.readthedocs.com/platform/stable/build-customization.html

Install dependencies from a specific group named 'docs' using pip version 25.1+. Note that overriding the install step requires manual pip upgrades.

```yaml
version: 2

build:
   os: ubuntu-24.04
   tools:
      python: "3.13"
   jobs:
      install:
         # Since the install step is overridden, pip is no longer updated automatically.
         - pip install --upgrade pip
         - pip install --group 'docs'


```

--------------------------------

### HTML Badge Example

Source: https://docs.readthedocs.com/platform/stable/badges.html

Example of how to embed a Read the Docs status badge in HTML format.

```html
<p><a href="https://readthedocs.org/projects/readthedocs/builds/"><img src="https://readthedocs.org/projects/readthedocs/badge/?version=latest" alt="Doc Status"></a></p>
```

--------------------------------

### Markdown Badge Example

Source: https://docs.readthedocs.com/platform/stable/badges.html

Example of how to embed a Read the Docs status badge in Markdown format.

```markdown
[![Doc Status](https://readthedocs.org/projects/readthedocs/badge/?version=latest)](https://readthedocs.org/projects/readthedocs/builds/)
```

--------------------------------

### reStructuredText Badge Example

Source: https://docs.readthedocs.com/platform/stable/badges.html

Example of how to embed a Read the Docs status badge in reStructuredText format.

```rst
.. image:: https://readthedocs.org/projects/readthedocs/badge/?version=latest
   :target: https://readthedocs.org/projects/readthedocs/builds/
   :alt: Documentation Status
```

--------------------------------

### Build All Formats

Source: https://docs.readthedocs.com/platform/stable/config-file/v2.html

Configures the build to generate all supported documentation formats using the 'all' keyword.

```yaml
version: 2

# Build all formats
formats: all

```

--------------------------------

### Install Package with Extra Requirements

Source: https://docs.readthedocs.com/platform/stable/config-file/v2.html

Installs the current Python package along with specified extra requirements, using pip.

```yaml
version: 2

python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

```

--------------------------------

### Update Redirect Body JSON Example

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

An example JSON payload for updating a redirect. Note that not all fields are required for an update.

```json
{
    "from_url": "/docs/",
    "to_url": "/documentation.html",
    "type": "page"
}

```

--------------------------------

### List Project Versions (Bash)

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

Use this command to retrieve a list of all versions for a specific project. Replace `<token>` with your API token.

```bash
$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/versions/

```

--------------------------------

### Get Build Details

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

Retrieve details of a single build for a project. Use the 'expand=config' query parameter to include configuration details.

```bash
$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/builds/8592686/?expand=config

```

--------------------------------

### Example JSON Body for Project Import

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

This is an example of the JSON object required in the request body when importing a project via the API.

```json
{
    "name": "Test Project",
    "repository": {
        "url": "https://github.com/readthedocs/template",
        "type": "git"
    },
    "homepage": "http://template.readthedocs.io/",
    "programming_language": "py",
    "language": "es",
    "privacy_level": "public",
    "external_builds_privacy_level": "public",
    "readthedocs_yaml_path": "docs/.readthedocs.yaml",
    "tags": [
        "automation",
        "sphinx"
    ]
}
```

--------------------------------

### Import Project (Bash)

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

This Bash command initiates a POST request to import a new project. It requires an authentication token and a JSON body file.

```bash
$ curl \
  -X POST \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/ \
  -H "Content-Type: application/json" \
  -d @body.json
```

--------------------------------

### MyST Markdown Notebook Example

Source: https://docs.readthedocs.com/platform/stable/guides/jupyter.html

An example of a notebook converted to MyST Markdown format, including metadata and kernel information.

```markdown
---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.10.3
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---


```

--------------------------------

### Enable PDF and EPUB Builds

Source: https://docs.readthedocs.com/platform/stable/tutorial/index.html

Configure Read the Docs to build PDF and EPUB formats in addition to HTML. This provides offline reading options for your users.

```yaml
sphinx:
  configuration: docs/source/conf.py
  fail_on_warning: true

formats:
  - pdf
  - epub


```

--------------------------------

### Installing MyST Parser for Markdown Support

Source: https://docs.readthedocs.com/platform/stable/intro/sphinx.html

Install the myst-parser package to enable writing documentation in Markdown files within a Sphinx project.

```bash
pip install myst-parser

```

--------------------------------

### Root URL Redirect Example

Source: https://docs.readthedocs.com/platform/stable/user-defined-redirects.html

Demonstrates how a link to the root of a documentation project redirects to the default version.

```text
docs.readthedocs.io -> docs.readthedocs.io/en/stable/
```

--------------------------------

### Redirect Body JSON Example

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

This is an example of the JSON payload required when creating or updating a redirect. The fields used depend on the `type` of redirect.

```json
{
    "from_url": "/docs/",
    "to_url": "/documentation/",
    "type": "page",
    "position": 0,
    "force": false,
    "enabled": true,
    "description": "Redirect old docs to new location",
    "http_status": 302
}

```

--------------------------------

### Direct Embed API Call Example 1

Source: https://docs.readthedocs.com/platform/stable/guides/embedding-content.html

Demonstrates a direct call to the Read the Docs Embed API to fetch content, specifically for automatic documentation deployment.

```http
https://app.readthedocs.org/api/v3/embed/?url=https://docs.readthedocs.io/en/stable/features.html%23automatic-documentation-deployment
```

--------------------------------

### Subproject Create Payload Example

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

This is an example of the JSON payload required when creating a subproject relationship. The `child` field is mandatory, while `alias` is optional.

```json
{
    "child": "subproject-child-slug",
    "alias": "subproject-alias"
}
```

--------------------------------

### Install Python Dependencies

Source: https://docs.readthedocs.com/platform/stable/tutorial/index.html

Specify Python dependencies to be installed before building documentation. This ensures that all necessary packages, including your project's code, are available.

```yaml
python:
  install:
    - requirements: docs/requirements.txt
    # Install our python package before building the docs
    - method: pip
      path: .


```

--------------------------------

### Create Project

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

Imports a project under the authenticated user. Requires repository URL and project name.

```APIDOC
## POST /api/v3/projects/

### Description
Import a project under authenticated user.

### Method
POST

### Endpoint
/api/v3/projects/

### Parameters
#### Request Body
- **name** (string) - Required - The name of the project to import.
- **repository** (object) - Required - Information about the project's repository.
  - **url** (string) - Required - The URL of the repository.
  - **type** (string) - Required - The type of the repository (e.g., "git").
- **homepage** (string) - Optional - The homepage URL of the project.
- **programming_language** (string) - Optional - The programming language of the project (e.g., "py").
- **language** (string) - Optional - The language code of the project (e.g., "es").
- **privacy_level** (string) - Optional - The privacy level of the project (e.g., "public"). Only available in Read the Docs Business.
- **external_builds_privacy_level** (string) - Optional - The privacy level for external builds. Only available in Read the Docs Business.
- **readthedocs_yaml_path** (string) - Optional - The path to the .readthedocs.yaml configuration file.
- **tags** (array of strings) - Optional - A list of tags for the project.
- **organization** (string) - Required (Read the Docs Business only) - The organization's slug under which the project will be imported.
- **teams** (array of strings) - Optional (Read the Docs Business only) - Slugs of the teams the project will belong to.

### Request Example
```bash
curl \
  -X POST \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/ \
  -H "Content-Type: application/json" \
  -d @body.json
```

```json
{
    "name": "Test Project",
    "repository": {
        "url": "https://github.com/readthedocs/template",
        "type": "git"
    },
    "homepage": "http://template.readthedocs.io/",
    "programming_language": "py",
    "language": "es",
    "privacy_level": "public",
    "external_builds_privacy_level": "public",
    "readthedocs_yaml_path": "docs/.readthedocs.yaml",
    "tags": [
        "automation",
        "sphinx"
    ]
}
```

### Response
See Project details
```

--------------------------------

### Push source files to Transifex

Source: https://docs.readthedocs.com/platform/stable/guides/manage-translations-sphinx.html

Upload your documentation's source translation files (.pot) to the Transifex platform. This makes them available for translators.

```bash
tx push --source

```

--------------------------------

### Install Dependencies with uv

Source: https://docs.readthedocs.com/platform/stable/build-customization.html

Configure `python.install` to use `uv` for dependency installation, respecting `uv.lock` if present. This method is preferred over overriding `build.jobs` for standard workflows.

```yaml
version: 2

build:
  os: ubuntu-24.04
  tools:
    python: "3.13"

python:
  install:
    - method: uv
      command: sync
      groups:
        - docs

sphinx:
    configuration: docs/conf.py


```

--------------------------------

### List Project Versions (Python)

Source: https://docs.readthedocs.com/platform/stable/api/v3.html

Use this Python script to programmatically fetch all versions for a project. Ensure you replace `<token>` with your actual API token.

```python
import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/versions/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

```

--------------------------------

### Sphinx Orphan Warning Example

Source: https://docs.readthedocs.com/platform/stable/guides/technical-docs-seo-guide.html

This is an example of a Sphinx build warning indicating an unreferenced page (orphan). Ensure your builds fail on warnings to catch these issues.

```bash
$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.8.5
...
checking consistency... /path/to/file.rst: WARNING: document isn't included in any toctree
done
...
build finished with problems, 1 warning.


```
Tokens:
Raw