• 
      

    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