Rework the RBTools docs for new installation steps and improved content.

Review Request #13002 — Created May 2, 2023 and submitted — Latest diff uploaded

Information

RBTools
release-4.x

Reviewers

This makes a handful of mostly-related changes to the RBTools
documentation, with an eye toward improving the front page of the docs
and walking people through installation (making use of more modern,
safer methods to install RBTools).

The front page of the docs used to be quite verbose, with a lot of
disconnected sections. This has been paired down considerably, offering
a more guided flow:

  • Introduction, with a reference to useful subsections
  • What's in RBTools?
  • Getting Started
  • Common RBTools Workflows

The new "Getting Started" section provides high-level step-by-step
instructions for setting up Review Board:

  • Link to installation docs
  • Link to the authentication docs
  • Link to the RBTools repository configuration docs
  • Link to docs on further customizing RBTools.

Those consolidate the various sections we had before into a guided tour.

The biggest change is the introduction of a page for installing RBTools.
This walks through three installation options:

  1. Official installer (Windows only for now)
  2. Using pipx (which is important on newer Linux systems following
    PEP 668)
  3. Using Python pip (for managed environments)

These attempt to guide the user to the right choice for their system. We
make use of Sphinx tabs to list the right steps for their OS.

The pipx steps are very important going forward, and are recommended
over pip, due to changes happening in newer distributions designed to
keep a pip install from breaking system packages.

pipx, while not installed by default, is a handy tool that will pull
down a package into a dedicated virtual environment and set up scripts
in a shared directory in your path. This is a good fit for RBTools for
most users.

Built the docs and viewed them in the docs UI.

Checked for build errors, spelling errors, and bad links.

Tested the install steps in VMs.

Commits

Files