• 
      

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

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

    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.

    Summary ID
    Rework the RBTools docs for new installation steps and improved content.
    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.
    4527173385c8753998455a5056493e35c99232aa
    chipx86
    david
    1. Ship It!
    2. 
        
    chipx86
    Review request changed
    Status:
    Completed
    Change Summary:
    Pushed to release-4.x (caa8790)