Summary

Rework the documentation on management commands.

Review Request #13001 — Created May 1, 2023 and submitted June 19, 2023, 9:26 p.m.

Information

Owner

chipx86

Repository

Review Board

Branch

release-5.0.x

Bugs

Depends On

Reviewers

Groups

reviewboard

People

Description

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.

Testing Done

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

Commits

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

Summary

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

Issues

Description	From	Last Updated
expected 2 blank lines, found 1 Column: 1 Error code: E302	reviewbot	May 19, 2023, 4:51 p.m.
I realize these are alphabetical, but I think it would make more sense for resolve-check to be last.	david	May 19, 2023, 4:36 p.m.
Is it worth clarifying here that periodic/scheduled indexing is only required if on-the-fly indexing is turned off?	david	May 19, 2023, 4:51 p.m.
Typo "output" -> "outputted"	maubin	June 19, 2023, 2:42 p.m.
Wouldn't the option be -m 10 for 10 minutes? And -a 1 is 1 hour?	maubin	June 19, 2023, 3 p.m.

flake8 failed.

JSHint passed.

flake8

docs/manual/_ext/rbwebsite_refs.py (Diff revision 1)

Show all issues

expected 2 blank lines, found 1

Column: 1
Error code: E302

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.

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?

Change Summary:


Updated ordering of some items in the siteconfig section's summary to make more logical sense.
Added a note about not needing periodic updates if on-the-fly indexing is enabled for search.

Commits:

	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.	79283ee5bfb14b94b8e1e37c12ab2814b88de8da
	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.	d101808c16875e93dd4ddfe4c20e9f61cb0fb19e

Diff:

Revision 2 (+1532 -136)

Show changes

	docs/manual/conf.py
	docs/manual/_ext/rbwebsite_refs.py
	docs/manual/admin/extensions/index.rst
	docs/manual/admin/sites/management-commands.rst
	reviewboard/cmdline/rbsite.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

docs/manual/admin/sites/management-commands.rst (Diff revision 2)
Show all issues
```
Typo "output" -> "outputted"
```

docs/manual/admin/sites/management-commands.rst (Diff revision 2)

Show all issues

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

chipx86 June 19, 2023, 3 p.m.

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.

Change Summary:


Fixed a typo.
Clarified the difference between -a <HOURS> and the task schedule timing for update_index.

Commits:

	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.	d101808c16875e93dd4ddfe4c20e9f61cb0fb19e
	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

Diff:

Revision 3 (+1544 -136)

Show changes

	docs/manual/conf.py
	docs/manual/_ext/rbwebsite_refs.py
	docs/manual/admin/extensions/index.rst
	docs/manual/admin/sites/management-commands.rst
	reviewboard/cmdline/rbsite.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Status: Closed (submitted)

Change Summary:

Pushed to release-5.0.x (7d445c2)