Rework the RBTools docs for new installation steps and improved content.
Review Request #13002 — Created May 2, 2023 and submitted
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:
- Official installer (Windows only for now)
- Using pipx (which is important on newer Linux systems following
- 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.
pipx steps are very important going forward, and are recommended
pip, due to changes happening in newer distributions designed to
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
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.
Updated with common fallback instructions for using
pipxpackages aren't available.
Revision 2 (+520 -118)
Checks run (2 succeeded)