Add documentation for the rbt commands
Review Request #3931 — Created March 5, 2013 and submitted
Add documentation for the rbt commands A page for each command has been added listing a short description and the options which the command accepts. Eventually these should be expanded to provide more in depth documentation. Also, the post-review documentation has been ported from the Review Board code base. This also served as the starting point for the rbt post command's documentation. Additionally, a couple of unused options, which were noticed while documenting, were removed from the post command. This is dependent upon /r/3296
Built the documentation using 'make html' and visually inspected.
| Description | From | Last Updated |
|---|---|---|
|
nit - even -> ever |
 mike_conley
|
|
|
I think "setuptools" should be lower-cased. |
 david
|
|
|
We should say "2.4 or higher," explicitly, in case some crazy person is using something even older. |
 chipx86
|
|
|
Up until here, you've been capitalizing the "s" in Setuptools. I guess do that here too. |
mike_conley
|
|
|
a browser -> the default web browser |
mike_conley
|
|
|
"If you instead" is a little awkward - maybe "If you want to update an existing review request with new … |
mike_conley
|
|
|
to generate -> to also generate |
mike_conley
|
|
|
made between ``topicB`` and ``topicA`` |
mike_conley
|
|
|
uuid -> UUID |
mike_conley
|
|
|
Not sure if this last paragraph is needed. And if so, it should link to where we mentioned updating review … |
mike_conley
|
|
|
You mention dotfiles earlier - I wonder if this should be the first solution you present instead. |
mike_conley
|
|
|
Not sure this is the clearest title. Maybe something like: Options for Setting Fields |
mike_conley
|
|
|
You've used "username" elsewhere. We'd better be consistent, so maybe go with "username". |
mike_conley
|
|
|
Maybe (again) mention, "if not supplied, defaults to 'submitted'" |
mike_conley
|
|
|
accompanied with change -> accompanying the change. |
mike_conley
|
|
|
username |
mike_conley
|
|
|
Typo: ouput I think it would be clearer if it said "print the diff to standard out" instead of "output … |
david
|
|
|
typo: ouput -> output |
mike_conley
|
|
|
git -> Git |
mike_conley
|
|
|
git -> Git x2 |
mike_conley
|
|
|
username |
mike_conley
|
|
|
username |
mike_conley
|
|
|
I think before this section, you should have a very simple section for Git/hg that just talks about using post … |
david
|
|
|
to generate -> to also generate |
mike_conley
|
|
|
made between ``topicB`` and ``topicA`` |
mike_conley
|
|
|
UUID |
mike_conley
|
|
|
Not sure if this last paragraph is needed. And if so, it should link to where we mentioned updating review … |
mike_conley
|
|
|
You mention dotfiles earlier - I wonder if this should be the first solution you present instead. |
mike_conley
|
|
|
git -> Git |
mike_conley
|
|
|
username |
mike_conley
|
|
|
username |
mike_conley
|
|
|
I'd like us to standardize on using review-request-id in all these cases. This applies to each occurrence. |
chipx86
|
-
-
-
-
docs/rbt/commands/diff.txt (Diff revision 1) Typo: ouput I think it would be clearer if it said "print the diff to standard out" instead of "output the diff"
-
docs/rbt/commands/post.txt (Diff revision 1) I think before this section, you should have a very simple section for Git/hg that just talks about using post with -g and -r to post/update code against a master branch.
-
Looks really good, Steven! Reads very well. Consider this a conditional ship-it - so if the below is addressed, I'm happy. :) Thanks, -Mike
-
-
docs/index.txt (Diff revision 1) Up until here, you've been capitalizing the "s" in Setuptools. I guess do that here too.
-
-
docs/post-review.txt (Diff revision 1) "If you instead" is a little awkward - maybe "If you want to update an existing review request with new changes instead,"
-
-
-
-
docs/post-review.txt (Diff revision 1) Not sure if this last paragraph is needed. And if so, it should link to where we mentioned updating review requests.
-
-
docs/post-review.txt (Diff revision 1) You mention dotfiles earlier - I wonder if this should be the first solution you present instead.
-
docs/post-review.txt (Diff revision 1) Not sure this is the clearest title. Maybe something like: Options for Setting Fields
-
docs/rbt/commands/attach.txt (Diff revision 1) You've used "username" elsewhere. We'd better be consistent, so maybe go with "username".
-
docs/rbt/commands/close.txt (Diff revision 1) Maybe (again) mention, "if not supplied, defaults to 'submitted'"
-
-
-
-
-
-
-
-
-
-
-
docs/rbt/commands/post.txt (Diff revision 1) Not sure if this last paragraph is needed. And if so, it should link to where we mentioned updating review requests.
-
docs/rbt/commands/post.txt (Diff revision 1) You mention dotfiles earlier - I wonder if this should be the first solution you present instead.
-
-
-
SM
Change Summary:
Updated based on reviews from David and Mike. Also broke the configuration information out of the post commands documentation and moved it to a separate rbt configuration documentation page. There were also two command options removed from post which were not being used.
Description: |
|
||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Diff: |
Revision 2 (+2004 -47) |
-
This is a review from Review Bot. Tool: PEP8 Style Checker Processed Files: rbtools/commands/post.py Ignored Files: docs/rbt/commands/attach.txt docs/post-review.txt docs/index.txt docs/rbt/commands/close.txt docs/rbt/commands/post.txt docs/rbt/commands/patch.txt docs/api/index.txt docs/rbt/commands/index.txt docs/rbt/commands/publish.txt docs/rbt/index.txt docs/api/overview.txt docs/contents.txt docs/rbt/configuration.txt docs/glossary.txt docs/rbt/commands/status.txt docs/rbt/commands/diff.txt
-
-
docs/index.txt (Diff revision 1) We should say "2.4 or higher," explicitly, in case some crazy person is using something even older.
-
-
docs/rbt/commands/attach.txt (Diff revision 2) I'd like us to standardize on using review-request-id in all these cases. This applies to each occurrence.
SM
Change Summary:
Updated based on Christian's reviews. Also changed the usage strings in the commands to be consistent with the doc change.
Diff: |
Revision 3 (+2009 -51) |
|---|
-
This is a review from Review Bot. Tool: PEP8 Style Checker Processed Files: rbtools/commands/patch.py rbtools/commands/post.py rbtools/commands/attach.py rbtools/commands/publish.py rbtools/commands/close.py Ignored Files: docs/rbt/commands/attach.txt docs/post-review.txt docs/index.txt docs/rbt/commands/close.txt docs/rbt/commands/post.txt docs/rbt/commands/patch.txt docs/api/index.txt docs/rbt/commands/index.txt docs/rbt/commands/publish.txt docs/rbt/index.txt docs/api/overview.txt docs/contents.txt docs/rbt/configuration.txt docs/glossary.txt docs/rbt/commands/status.txt docs/rbt/commands/diff.txt
This is a review from Review Bot. Tool: PEP8 Style Checker Processed Files: Ignored Files: docs/rbt/commands/attach.txt docs/api/overview.txt docs/index.txt docs/rbt/commands/close.txt docs/rbt/commands/post.txt docs/rbt/commands/patch.txt docs/api/index.txt docs/rbt/commands/index.txt docs/rbt/commands/publish.txt docs/rbt/index.txt docs/post-review.txt docs/contents.txt docs/glossary.txt docs/rbt/commands/status.txt docs/rbt/commands/diff.txt