Rework the documentation on management commands.

Review Request #13001 — Created May 1, 2023 and submitted

Information

Review Board
release-5.0.x

Reviewers

Our documentation on management commands was very limited, listing only
a few commands and in no specific order.

This change completely reworks the documentation to list all common
commands we display in rb-site manage --help. They go over basic
usage and options, show warnings for the more dangerous commands, and
provide links to useful reference docs.

Each set of commands are listed in a dedicated section, providing
organization.

There's a new rb-management-command directive and role, which will
make it easier to link to the necessary docs without using :ref:.

Two commands, find-large-diffs and invalidate-api-tokens, have been
added to the mange rb-site manage --help output.

Built the docs. Checked for build errors, spelling errors, and bad
links. Viewed them in the new docs UI.

Summary ID
Rework the documentation on management commands.
Our documentation on management commands was very limited, listing only a few commands and in no specific order. This change completely reworks the documentation to list all common commands we display in `rb-site manage --help`. They go over basic usage and options, show warnings for the more dangerous commands, and provide links to useful reference docs. Each set of commands are listed in a dedicated section, providing organization. There's a new `rb-management-command` directive and role, which will make it easier to link to the necessary docs without using `:ref:`. Two commands, `find-large-diffs` and `invalidate-api-tokens`, have been added to the mange `rb-site manage --help` output.
76cd62723214038dbcf0320e079a18684729c1a7
Description From Last Updated

expected 2 blank lines, found 1 Column: 1 Error code: E302

reviewbotreviewbot

I realize these are alphabetical, but I think it would make more sense for resolve-check to be last.

daviddavid

Is it worth clarifying here that periodic/scheduled indexing is only required if on-the-fly indexing is turned off?

daviddavid

Typo "output" -> "outputted"

maubinmaubin

Wouldn't the option be -m 10 for 10 minutes? And -a 1 is 1 hour?

maubinmaubin
Checks run (1 failed, 1 succeeded)
flake8 failed.
JSHint passed.

flake8

david
  1. 
      
  2. docs/manual/admin/sites/management-commands.rst (Diff revision 1)
     
     
     
     
     
     
    Show all issues

    I realize these are alphabetical, but I think it would make more sense for resolve-check to be last.

  3. docs/manual/admin/sites/management-commands.rst (Diff revision 1)
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
    Show all issues

    Is it worth clarifying here that periodic/scheduled indexing is only required if on-the-fly indexing is turned off?

  4. 
      
chipx86
david
  1. Ship It!
  2. 
      
maubin
  1. 
      
  2. Show all issues

    Typo "output" -> "outputted"

  3. Show all issues

    Wouldn't the option be -m 10 for 10 minutes? And -a 1 is 1 hour?

    1. Yeah, though those just control the timestamp range. The goal here is to update the search index every 10 minutes, but to consider any item with a timestamp from the past hour. That gives some buffer room, helping avoid something from being missed due to, say, a reboot, or a temporary outage.

      Reworking the docs to be more clear here.

  4. 
      
chipx86
maubin
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to release-5.0.x (7d445c2)