Summary

Rearrange RBTools documentation a bit.

Review Request #14348 — Created Feb. 14, 2025 and updated 4 days, 1 hour ago

Information

Owner

david*

Repository

RBTools

Branch

master

Bugs

Depends On

Reviewers

Groups

rbtools

People

Description*

This change rearranges the RBTools documentation to try to simplify some
things:

Moved info about .reviewboardrc files to the main "configuration"
page, and clarified where different files are loaded from and in what
priority order.
Updated repo configuration page to emphasize why a .reviewboardrc file
is a good idea and moved the alternative methods up next to that so
it's clear what they're for.
Moved the ENABLE_PROXY documentation from repository config to user
config.
Split the docs about aliases out into its own page.
On the main index page, simplified the "Getting Started" section to be
install, configure, use.
Moved links for authentication and TFS into the "Common RBTools
workflows" section.

Testing Done

Built docs and checked the results.

Commits

Summary	ID
Rearrange RBTools documentation a bit. This change rearranges the RBTools documentation to try to simplify some things: - Moved info about .reviewboardrc files to the main "configuration" page, and clarified where different files are loaded from and in what priority order. - Updated repo configuration page to emphasize why a .reviewboardrc file is a good idea and moved the alternative methods up next to that so it's clear what they're for. - Moved the `ENABLE_PROXY` documentation from repository config to user config. - Split the docs about aliases out into its own page. - On the main index page, simplified the "Getting Started" section to be install, configure, use. - Moved links for authentication and TFS into the "Common RBTools workflows" section. Testing Done: Built docs and checked the results.	fb1970dbc1e9139ddfafef22255cc2214639ea2b

Summary

Rearrange RBTools documentation a bit.

This change rearranges the RBTools documentation to try to simplify some things: - Moved info about .reviewboardrc files to the main "configuration" page, and clarified where different files are loaded from and in what priority order. - Updated repo configuration page to emphasize why a .reviewboardrc file is a good idea and moved the alternative methods up next to that so it's clear what they're for. - Moved the `ENABLE_PROXY` documentation from repository config to user config. - Split the docs about aliases out into its own page. - On the main index page, simplified the "Getting Started" section to be install, configure, use. - Moved links for authentication and TFS into the "Common RBTools workflows" section. Testing Done: Built docs and checked the results.

fb1970dbc1e9139ddfafef22255cc2214639ea2b

Issues

Description	From	Last Updated
Can we reference the config for ALIASES? If there's a ref name for that.	chipx86	4 days, 5 hours ago
I think for each of these, we should provide a concrete example to drive it home. It's otherwise a bit …	chipx86	4 days, 5 hours ago
Extra blank line at the end of the file.	chipx86	4 days, 5 hours ago
I think the parsing bit might be good as an important admonition.	chipx86	4 days, 5 hours ago
This and the section below should be in Title Case, to match other sections.	chipx86	4 days, 5 hours ago
Maybe "If for some reason you can't ...", to help this feel a bit more plain-spoken for readers.	chipx86	4 days, 5 hours ago
There are no open issues

flake8 passed.

JSHint passed.

docs/rbtools/rbt/configuration/aliases.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
Can we reference the config for ALIASES? If there's a ref name for that.
```

docs/rbtools/rbt/configuration/aliases.rst (Diff revision 1)

The issue has been resolved. Show all issues

I think for each of these, we should provide a concrete example to drive it home. It's otherwise a bit unclear without already knowing about these topics.

I think it may also be worth splitting up the paragraph into each main point (e.g., System Command Aliases could explain how they're set, then that they're flexible/dangerous, and then that everything is passed to the shell).

docs/rbtools/rbt/configuration/aliases.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
Extra blank line at the end of the file.
```
docs/rbtools/rbt/configuration/index.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
I think the parsing bit might be good as an important admonition.
```
docs/rbtools/rbt/configuration/repositories.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
This and the section below should be in Title Case, to match other sections.
```
docs/rbtools/rbt/configuration/repositories.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
Maybe "If for some reason you can't ...", to help this feel a bit more plain-spoken for readers.
```

Commits:

	Summary	ID
	Rearrange RBTools documentation a bit. This change rearranges the RBTools documentation to try to simplify some things: - Moved info about .reviewboardrc files to the main "configuration" page, and clarified where different files are loaded from and in what priority order. - Updated repo configuration page to emphasize why a .reviewboardrc file is a good idea and moved the alternative methods up next to that so it's clear what they're for. - Moved the `ENABLE_PROXY` documentation from repository config to user config. - Split the docs about aliases out into its own page. - On the main index page, simplified the "Getting Started" section to be install, configure, use. - Moved links for authentication and TFS into the "Common RBTools workflows" section. Testing Done: Built docs and checked the results.	ad6dbc5ba05b5b36aec29e681f5c75e141833bfe
	Rearrange RBTools documentation a bit. This change rearranges the RBTools documentation to try to simplify some things: - Moved info about .reviewboardrc files to the main "configuration" page, and clarified where different files are loaded from and in what priority order. - Updated repo configuration page to emphasize why a .reviewboardrc file is a good idea and moved the alternative methods up next to that so it's clear what they're for. - Moved the `ENABLE_PROXY` documentation from repository config to user config. - Split the docs about aliases out into its own page. - On the main index page, simplified the "Getting Started" section to be install, configure, use. - Moved links for authentication and TFS into the "Common RBTools workflows" section. Testing Done: Built docs and checked the results.	fb1970dbc1e9139ddfafef22255cc2214639ea2b

Diff:

Revision 2 (+476 -406)

Show changes

	docs/rbtools/rbt/configuration/authentication.rst
	docs/rbtools/index.rst
	docs/rbtools/rbt/configuration/aliases.rst
	docs/rbtools/rbt/configuration/index.rst
	docs/rbtools/rbt/configuration/repositories.rst
	docs/rbtools/rbt/configuration/users.rst

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```