readthedocs-cli 3

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/*