Summary

Add documentation for the rbt commands

Review Request #3931 — Created March 5, 2013 and submitted March 12, 2013, 10:40 p.m.

Information

Owner

smacleod

Repository

RBTools

Branch

master

Bugs

Depends On

Reviewers

Groups

rbtools

People

chipx86, david

Description

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

Testing Done

Built the documentation using 'make html' and visually inspected.

Issues

Description	From	Last Updated
nit - even -> ever	mike_conley	March 12, 2013, 9:09 p.m.
I think "setuptools" should be lower-cased.	david	March 12, 2013, 9:06 p.m.
We should say "2.4 or higher," explicitly, in case some crazy person is using something even older.	chipx86	March 12, 2013, 10:27 p.m.
Up until here, you've been capitalizing the "s" in Setuptools. I guess do that here too.	mike_conley	March 12, 2013, 9:10 p.m.
a browser -> the default web browser	mike_conley	March 12, 2013, 9:11 p.m.
"If you instead" is a little awkward - maybe "If you want to update an existing review request with new …	mike_conley	March 12, 2013, 9:12 p.m.
to generate -> to also generate	mike_conley	March 12, 2013, 9:14 p.m.
made between ``topicB`` and ``topicA``	mike_conley	March 12, 2013, 9:18 p.m.
uuid -> UUID	mike_conley	March 12, 2013, 9:18 p.m.
Not sure if this last paragraph is needed. And if so, it should link to where we mentioned updating review …	mike_conley	March 12, 2013, 9:19 p.m.
You mention dotfiles earlier - I wonder if this should be the first solution you present instead.	mike_conley	March 12, 2013, 9:22 p.m.
Not sure this is the clearest title. Maybe something like: Options for Setting Fields	mike_conley	March 12, 2013, 9:24 p.m.
You've used "username" elsewhere. We'd better be consistent, so maybe go with "username".	mike_conley	March 12, 2013, 9:25 p.m.
Maybe (again) mention, "if not supplied, defaults to 'submitted'"	mike_conley	March 12, 2013, 9:26 p.m.
accompanied with change -> accompanying the change.	mike_conley	March 12, 2013, 9:28 p.m.
username	mike_conley	March 12, 2013, 9:28 p.m.
Typo: ouput I think it would be clearer if it said "print the diff to standard out" instead of "output …	david	March 12, 2013, 9:06 p.m.
typo: ouput -> output	mike_conley	March 12, 2013, 9:29 p.m.
git -> Git	mike_conley	March 12, 2013, 9:30 p.m.
git -> Git x2	mike_conley	March 12, 2013, 9:30 p.m.
username	mike_conley	March 12, 2013, 9:31 p.m.
username	mike_conley	March 12, 2013, 9:31 p.m.
I think before this section, you should have a very simple section for Git/hg that just talks about using post …	david	March 12, 2013, 9:52 p.m.
to generate -> to also generate	mike_conley	March 12, 2013, 9:31 p.m.
made between ``topicB`` and ``topicA``	mike_conley	March 12, 2013, 9:31 p.m.
UUID	mike_conley	March 12, 2013, 9:31 p.m.
Not sure if this last paragraph is needed. And if so, it should link to where we mentioned updating review …	mike_conley	March 12, 2013, 9:31 p.m.
You mention dotfiles earlier - I wonder if this should be the first solution you present instead.	mike_conley	March 12, 2013, 9:32 p.m.
git -> Git	mike_conley	March 12, 2013, 9:33 p.m.
username	mike_conley	March 12, 2013, 9:37 p.m.
username	mike_conley	March 12, 2013, 9:38 p.m.
I'd like us to standardize on using review-request-id in all these cases. This applies to each occurrence.	chipx86	March 12, 2013, 10:30 p.m.

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

docs/glossary.txt (Diff revision 1)

Instead of "goes into" I would say "gets checked in to"

docs/index.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
I think "setuptools" should be lower-cased.
```

docs/rbt/commands/diff.txt (Diff revision 1)

The issue has been resolved. 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"

docs/rbt/commands/post.txt (Diff revision 1)

The issue has been resolved. 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.

Ship it!

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/glossary.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
nit - even -> ever
```

docs/index.txt (Diff revision 1)

The issue has been dropped. Show all issues

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

smacleod

March 12, 2013, 10:08 p.m.

As David suggested, "setuptools" is usually not capitalized, so I'm switching all references to lower case.

docs/post-review.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
a browser -> the default web browser
```

docs/post-review.txt (Diff revision 1)

The issue has been resolved. Show all issues

"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)
The issue has been resolved. Show all issues
```
to generate -> to also generate
```
docs/post-review.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
made between ``topicB`` and ``topicA``
```
docs/post-review.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
uuid -> UUID
```

docs/post-review.txt (Diff revision 1)

The issue has been resolved. Show all issues

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)

I'm glad I don't use old versions of Perforce. :)

docs/post-review.txt (Diff revision 1)

The issue has been resolved. Show all issues

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

docs/post-review.txt (Diff revision 1)

The issue has been resolved. Show all issues

Not sure this is the clearest title.

Maybe something like:

Options for Setting Fields

docs/rbt/commands/attach.txt (Diff revision 1)

The issue has been resolved. Show all issues

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

docs/rbt/commands/close.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
Maybe (again) mention, "if not supplied, defaults to 'submitted'"
```
docs/rbt/commands/close.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
accompanied with change -> accompanying the change.
```
docs/rbt/commands/close.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
username
```
docs/rbt/commands/diff.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
typo: ouput -> output
```
docs/rbt/commands/diff.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
git -> Git
```
docs/rbt/commands/diff.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
git -> Git x2
```
docs/rbt/commands/diff.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
username
```
docs/rbt/commands/patch.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
username
```
docs/rbt/commands/post.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
to generate -> to also generate
```
docs/rbt/commands/post.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
made between ``topicB`` and ``topicA``
```
docs/rbt/commands/post.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
UUID
```

docs/rbt/commands/post.txt (Diff revision 1)

The issue has been resolved. Show all issues

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)

The issue has been resolved. Show all issues

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

docs/rbt/commands/post.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
git -> Git
```
docs/rbt/commands/publish.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
username
```
docs/rbt/commands/status.txt (Diff revision 1)
The issue has been resolved. Show all issues
```
username
```

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:

		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

Diff:

Revision 2 (+2004 -47)

Show changes

	docs/contents.txt
	docs/glossary.txt
	docs/index.txt
	docs/post-review.txt
	docs/api/index.txt
	docs/api/overview.txt
	docs/rbt/configuration.txt
	docs/rbt/index.txt
	9 more

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)

The issue has been resolved. Show all issues

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)

The issue has been resolved. Show all issues

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

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)

Show changes

	docs/contents.txt
	docs/glossary.txt
	docs/index.txt
	docs/post-review.txt
	docs/api/index.txt
	docs/api/overview.txt
	docs/rbt/configuration.txt
	docs/rbt/index.txt
	13 more

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

Ship it!

```
Ship It!
```

Status:: Completed
Change Summary:: Pushed to master (49166f91eac5f91bca7779337e1a7d405ef54878).