Skip to main content

A CLI for the Read The Docs v3 API

Project description

A work in progress.

Made to sync RTD project redirects and maintainers from authoritative files kept in version control. May never do anything else!

Synopsis

Provide an RTD API token via the environment:

$ export RTD_TOKEN=

List projects:

$ rtd projects
nextstrain
├── nextstrain-ncov
├── nextstrain-nextclade
├── nextstrain-augur
├── nextstrain-auspice
├── nextstrain-cli
└── nextstrain-sphinx-theme

Show a project (very sparse currently):

$ rtd projects nextstrain
nextstrain <https://docs.nextstrain.org/en/latest/>

Show a project’s redirects:

$ rtd projects nextstrain redirects
                                                                             Redirects

  Type   From URL                                                     To URL
 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  page   /guides/                                                     /
  page   /guides/index.html                                           /index.html
  page   /guides/install/                                             install-nextstrain.html
  page   /guides/install/augur_install.html                           https://docs.nextstrain.org/projects/augur/en/stable/installation/installation.html
  page   /guides/install/auspice-install                              https://docs.nextstrain.org/projects/auspice/en/stable/introduction/install.html
  page   /guides/install/auspice-install.html                         https://docs.nextstrain.org/projects/auspice/en/stable/introduction/install.html
  page   /guides/install/cli-install.html                             https://docs.nextstrain.org/projects/cli/en/latest/installation/
  page   /guides/install/index.html                                   install-nextstrain.html
  page   /guides/install/local-installation.html                      install-nextstrain.html
  page   /guides/install/windows-help.html                            install-nextstrain.html
  page   /install-nextstrain.html                                     /install.html
  page   /learn/                                                      /
  page   /learn/about-nextstrain.html                                 /learn/about.html
  page   /learn/index.html                                            /index.html
  page   /reference/                                                  /
  page   /reference/formats/                                          /reference/data-formats.html
  page   /reference/formats/data-formats.html                         /reference/data-formats.html
  page   /reference/formats/index.html                                /reference/data-formats.html
  page   /reference/index.html                                        /index.html
  …

Sync a project’s redirects:

$ rtd projects nextstrain redirects sync -f redirects.yml
Creating: page /tutorials/quickstart.html → /tutorials/running-a-workflow.html
Creating: page /tutorials/tb_tutorial.html → /tutorials/creating-a-workflow-vcf.html
Creating: page /tutorials/zika.html → /tutorials/creating-a-workflow.html

          Created

  Type   From URL                      To URL
 ──────────────────────────────────────────────────────────────────────────────
  page   /tutorials/quickstart.html    /tutorials/running-a-workflow.html
  page   /tutorials/tb_tutorial.html   /tutorials/creating-a-workflow-vcf.html
  page   /tutorials/zika.html          /tutorials/creating-a-workflow.html

                                    Deleted

  Type   From URL   To URL
 ──────────────────────────

Created 3, deleted 0, kept 38.

No changes made in --dry-run mode.  Pass --wet-run for realsies.

Show a project’s maintainers:

$ rtd projects nextstrain maintainers
eharkins
huddlej
ivan.aksamentov
jameshadfield
misja
nextstrain
rneher
trs
trvrb
victorlin0

Sync a project’s maintainers:

$ rtd projects nextstrain maintainers sync -f rtd-maintainers.txt
- eharkins
• huddlej
• ivan.aksamentov
• jameshadfield
- misja
• nextstrain
• rneher
• trs
• trvrb
+ victorlin0

Added (+) 1, removed (-) 2, kept 7.

No changes made in --dry-run mode.  Pass --wet-run for realsies.

For automation or just the full details, ask for JSON output instead of human-centered output from any command:

$ rtd --json projects
[
  {
    "id": 607779,
    "name": "nextstrain",
    "created": "2020-05-28T00:25:49.630013Z",
    "modified": "2021-08-18T23:39:10.271300Z",
    "default_branch": "master",
    "default_version": "latest",
    "homepage": "https://nextstrain.org",
    "language": {
      "code": "en",
      "name": "English"
    },
    "programming_language": {
      "code": "words",
      "name": "Only Words"
    },
    "repository": {
      "type": "git",
      "url": "https://github.com/nextstrain/docs.nextstrain.org.git"
    },
    …
  },
  …
]

Install

From PyPI:

python3 -m pip install readthedocs-cli

From source:

python3 -m venv .venv
source .venv/bin/activate

python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install -e .

rtd --version

Automatic sync using GitHub Actions

We manage the RTD redirects for <https://docs.nextstrain.org> using a file in our Git repository, <https://github.com/nextstrain/docs.nextstrain.org>. The redirects are automatically synced to RTD via a GitHub Actions workflow that uses this CLI tool. It’s a good example of how to set up something similar for your own project. The pieces are:

  1. redirects.yml file — The redirects themselves, defined as YAML.

  2. .github/workflows/sync-redirects.yaml file — GitHub Actions workflow to sync to RTD when redirects.yml changes on the master branch.

  3. An RTD_TOKEN GitHub Actions secret containing an RTD API token.

Releasing

This is still a pretty informal piece of software, but it is released to PyPI so that we can easily install it various places.

The gist of the release process is:

  1. Bump the __version__ variable (just an integer) in src/readthedocs_cli/__init__.py.

  2. Commit, tag, and push.

  3. Build and upload.

    You’ll need build and twine installed.

    # Clear any existing build artifacts for safety
    rm -rf dist/
    
    # Build source tarball and platform-agnostic wheel
    python3 -m build
    
    # Upload both to PyPI
    twine upload dist/*

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

readthedocs_cli-5.tar.gz (10.8 kB view details)

Uploaded Source

Built Distribution

readthedocs_cli-5-py3-none-any.whl (9.9 kB view details)

Uploaded Python 3

File details

Details for the file readthedocs_cli-5.tar.gz.

File metadata

  • Download URL: readthedocs_cli-5.tar.gz
  • Upload date:
  • Size: 10.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.12.5

File hashes

Hashes for readthedocs_cli-5.tar.gz
Algorithm Hash digest
SHA256 5b62efd9fbf1b4620b20cceca083d10e9c5247c0ca73dd0e45a922ef5b425bab
MD5 e9dca9364e90cb43e568f5feda0df6ac
BLAKE2b-256 df408c213ddfc9eb59bea54adceaef9ecd4fdff786b6fdb1a91132d71cbb239d

See more details on using hashes here.

File details

Details for the file readthedocs_cli-5-py3-none-any.whl.

File metadata

  • Download URL: readthedocs_cli-5-py3-none-any.whl
  • Upload date:
  • Size: 9.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.12.5

File hashes

Hashes for readthedocs_cli-5-py3-none-any.whl
Algorithm Hash digest
SHA256 07e2bee9137adae68f15bd50e3245db249aa2782c6f848eaac3f46ea0f1c2b81
MD5 55b63dbad7fc918d4f34c82768dba299
BLAKE2b-256 e05cb8dc4e3640635d145aa23994e541b3d42998cff09a857dba1a499c5eba18

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page