readthedocs-cli

Command line client for Read the Docs. Build your documentation anywhere and upload the artifacts to Read the Docs for hosting.

Installation

uvx --from readthedocs-upload readthedocs --help
# or
pip install readthedocs-upload

Python 3.10 or newer is required.

Usage

export READTHEDOCS_TOKEN=...
readthedocs upload --project-slug my-project --html _build/html

Downloadable formats are optional and point at a single file each:

readthedocs upload \
    --project-slug my-project \
    --html _build/html \
    --pdf _build/latex/my-project.pdf \
    --epub _build/epub/my-project.epub

Run readthedocs upload --help for all options.

Environment variables

Version metadata

The client infers the version to upload from the environment. Every inferred value can be overridden with --version-name, --version-type and --commit.

Other CI providers work with the explicit flags.

GitHub Actions

On GitHub, use the readthedocs/upload-action, which wraps this client and resolves the Git metadata from the workflow event:

- uses: readthedocs/upload-action@v1
  with:
    token: ${{ secrets.READTHEDOCS_TOKEN }}
    project-slug: my-project
    html: _build/html

Development

git submodule update --init
uv sync
uv run readthedocs --help
uv run --with tox --with tox-uv tox