Add documentation for the rbt commands

Review Request #3931 — Created March 5, 2013 and submitted

Information

RBTools
master

Reviewers

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_conleymike_conley

I think "setuptools" should be lower-cased.

daviddavid

We should say "2.4 or higher," explicitly, in case some crazy person is using something even older.

chipx86chipx86

Up until here, you've been capitalizing the "s" in Setuptools. I guess do that here too.

mike_conleymike_conley

a browser -> the default web browser

mike_conleymike_conley

"If you instead" is a little awkward - maybe "If you want to update an existing review request with new …

mike_conleymike_conley

to generate -> to also generate

mike_conleymike_conley

made between ``topicB`` and ``topicA``

mike_conleymike_conley

uuid -> UUID

mike_conleymike_conley

Not sure if this last paragraph is needed. And if so, it should link to where we mentioned updating review …

mike_conleymike_conley

You mention dotfiles earlier - I wonder if this should be the first solution you present instead.

mike_conleymike_conley

Not sure this is the clearest title. Maybe something like: Options for Setting Fields

mike_conleymike_conley

You've used "username" elsewhere. We'd better be consistent, so maybe go with "username".

mike_conleymike_conley

Maybe (again) mention, "if not supplied, defaults to 'submitted'"

mike_conleymike_conley

accompanied with change -> accompanying the change.

mike_conleymike_conley

username

mike_conleymike_conley

Typo: ouput I think it would be clearer if it said "print the diff to standard out" instead of "output …

daviddavid

typo: ouput -> output

mike_conleymike_conley

git -> Git

mike_conleymike_conley

git -> Git x2

mike_conleymike_conley

username

mike_conleymike_conley

username

mike_conleymike_conley

I think before this section, you should have a very simple section for Git/hg that just talks about using post …

daviddavid

to generate -> to also generate

mike_conleymike_conley

made between ``topicB`` and ``topicA``

mike_conleymike_conley

UUID

mike_conleymike_conley

Not sure if this last paragraph is needed. And if so, it should link to where we mentioned updating review …

mike_conleymike_conley

You mention dotfiles earlier - I wonder if this should be the first solution you present instead.

mike_conleymike_conley

git -> Git

mike_conleymike_conley

username

mike_conleymike_conley

username

mike_conleymike_conley

I'd like us to standardize on using review-request-id in all these cases. This applies to each occurrence.

chipx86chipx86
reviewbot
  1. 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
    
    
  2. 
      
david
  1. 
      
  2. docs/glossary.txt (Diff revision 1)
     
     
     
    Instead of "goes into" I would say "gets checked in to"
  3. docs/index.txt (Diff revision 1)
     
     
    Show all issues
    I think "setuptools" should be lower-cased.
  4. docs/rbt/commands/diff.txt (Diff revision 1)
     
     
    Show all issues
    Typo: ouput
    
    I think it would be clearer if it said "print the diff to standard out" instead of "output the diff"
  5. docs/rbt/commands/post.txt (Diff revision 1)
     
     
     
     
     
     
    Show all issues
    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.
  6. 
      
mike_conley
  1. Looks really good, Steven! Reads very well. Consider this a conditional ship-it - so if the below is addressed, I'm happy. :)
    
    Thanks,
    
    -Mike
  2. docs/glossary.txt (Diff revision 1)
     
     
    Show all issues
    nit - even -> ever
  3. docs/index.txt (Diff revision 1)
     
     
    Show all issues
    Up until here, you've been capitalizing the "s" in Setuptools. I guess do that here too.
    1. As David suggested, "setuptools" is usually not capitalized, so I'm switching all references to lower case.
  4. docs/post-review.txt (Diff revision 1)
     
     
    Show all issues
    a browser -> the default web browser
  5. docs/post-review.txt (Diff revision 1)
     
     
     
    Show all issues
    "If you instead" is a little awkward - maybe "If you want to update an existing review request with new changes instead,"
  6. docs/post-review.txt (Diff revision 1)
     
     
    Show all issues
    to generate -> to also generate
  7. docs/post-review.txt (Diff revision 1)
     
     
    Show all issues
    made between ``topicB`` and ``topicA``
  8. docs/post-review.txt (Diff revision 1)
     
     
    Show all issues
    uuid -> UUID
  9. docs/post-review.txt (Diff revision 1)
     
     
     
    Show all issues
    Not sure if this last paragraph is needed. And if so, it should link to where we mentioned updating review requests.
  10. docs/post-review.txt (Diff revision 1)
     
     
    I'm glad I don't use old versions of Perforce. :)
  11. docs/post-review.txt (Diff revision 1)
     
     
     
     
     
     
     
     
    Show all issues
    You mention dotfiles earlier - I wonder if this should be the first solution you present instead.
  12. docs/post-review.txt (Diff revision 1)
     
     
     
    Show all issues
    Not sure this is the clearest title.
    
    Maybe something like:
    
    Options for Setting Fields
  13. docs/rbt/commands/attach.txt (Diff revision 1)
     
     
    Show all issues
    You've used "username" elsewhere. We'd better be consistent, so maybe go with "username".
  14. docs/rbt/commands/close.txt (Diff revision 1)
     
     
    Show all issues
    Maybe (again) mention, "if not supplied, defaults to 'submitted'"
  15. docs/rbt/commands/close.txt (Diff revision 1)
     
     
    Show all issues
    accompanied with change -> accompanying the change.
  16. docs/rbt/commands/close.txt (Diff revision 1)
     
     
    Show all issues
    username
  17. docs/rbt/commands/diff.txt (Diff revision 1)
     
     
    Show all issues
    typo: ouput -> output
  18. docs/rbt/commands/diff.txt (Diff revision 1)
     
     
    Show all issues
    git -> Git
  19. docs/rbt/commands/diff.txt (Diff revision 1)
     
     
     
    Show all issues
    git -> Git x2
  20. docs/rbt/commands/diff.txt (Diff revision 1)
     
     
    Show all issues
    username
  21. docs/rbt/commands/patch.txt (Diff revision 1)
     
     
    Show all issues
    username
  22. docs/rbt/commands/post.txt (Diff revision 1)
     
     
    Show all issues
    to generate -> to also generate
  23. docs/rbt/commands/post.txt (Diff revision 1)
     
     
    Show all issues
    made between ``topicB`` and ``topicA``
  24. docs/rbt/commands/post.txt (Diff revision 1)
     
     
    Show all issues
    UUID
  25. docs/rbt/commands/post.txt (Diff revision 1)
     
     
     
    Show all issues
    Not sure if this last paragraph is needed. And if so, it should link to where we mentioned updating review requests.
  26. docs/rbt/commands/post.txt (Diff revision 1)
     
     
    Show all issues
    You mention dotfiles earlier - I wonder if this should be the first solution you present instead.
  27. docs/rbt/commands/post.txt (Diff revision 1)
     
     
    Show all issues
    git -> Git
  28. docs/rbt/commands/publish.txt (Diff revision 1)
     
     
    Show all issues
    username
  29. docs/rbt/commands/status.txt (Diff revision 1)
     
     
    Show all issues
    username
  30. 
      
SM
reviewbot
  1. 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
    
    
  2. 
      
chipx86
  1. 
      
  2. docs/index.txt (Diff revision 1)
     
     
    Show all issues
    We should say "2.4 or higher," explicitly, in case some crazy person is using something even older.
  3. 
      
chipx86
  1. 
      
  2. docs/rbt/commands/attach.txt (Diff revision 2)
     
     
    Show all issues
    I'd like us to standardize on using review-request-id in all these cases. This applies to each occurrence.
  3. 
      
SM
reviewbot
  1. 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
    
    
  2. 
      
chipx86
  1. Ship It!
  2. 
      
SM
Review request changed
Status:
Completed
Change Summary:
Pushed to master (49166f91eac5f91bca7779337e1a7d405ef54878).