Introduce rbtools documentation

Review Request #3296 — Created Aug. 20, 2012 and submitted

Information

RBTools
master

Reviewers

Introduce rbtools documentation

Create the configuration for the rbtools documentation and introduce
the initial documentation for the rbtools api client. This
documentation includes a small tutorial, a general overview, and
resource specific functionality.
Built the documentation using 'make html' and visually inspected. Quickly proofread as I went.
Description From Last Updated

Might as well have this fit PEP-8. Space after the :

daviddavid

I think it would be easier to read and probably more useful if you showed this loading the diff from …

daviddavid

?

daviddavid

Same here re: loading from a file.

daviddavid

Maybe show what happens if you try to publish and there's no user or group assigned?

daviddavid

Maybe just link "hyperlinks" to this?

chipx86chipx86

Technically, all the keys in this would be quoted, since they do that in JSON.

chipx86chipx86

Got an extra space in here.

chipx86chipx86

"keyword"

chipx86chipx86

field's

chipx86chipx86

resource's ?

chipx86chipx86

administrator's

chipx86chipx86

Capitalize "Specify"

chipx86chipx86

Resource-Specific

chipx86chipx86

I'd maybe remove "Specific" on these sub-headers.

chipx86chipx86

"retrieve"

chipx86chipx86

Comma after "examples"

chipx86chipx86

"API", for consistency.

chipx86chipx86

Comma after ``uri-template``.

chipx86chipx86

Comma after ``uri-template``

chipx86chipx86

This looks left over from something.

chipx86chipx86

"Review Board"

chipx86chipx86

API?

chipx86chipx86

We have the room, so I'd suggest we have the first parameter on the "RBClient(" line.

chipx86chipx86

"documentation"

chipx86chipx86

I don't think that's true anymore. It should be possible to create a review request with no repository, for file …

chipx86chipx86

"ID"

chipx86chipx86

Two blank lines.

chipx86chipx86

Refs are going to use the page titles, which may not fit well in the sentence. I'd make sure to …

chipx86chipx86

resource's

chipx86chipx86

Comma after "attachment"

chipx86chipx86

4 space indentation, relative to the code's indentation block.

chipx86chipx86

Two blank lines.

chipx86chipx86

Indentation is wonky.

chipx86chipx86

No comma after "group"

chipx86chipx86

Comma after "requirement"

chipx86chipx86

Odd way to format a paragraph ;)

chipx86chipx86

Comma after "review request'

chipx86chipx86

Col: 80 E501 line too long (80 > 79 characters)

reviewbotreviewbot

Col: 80 E501 line too long (82 > 79 characters)

reviewbotreviewbot

Col: 11 E401 multiple imports on one line

reviewbotreviewbot

Col: 80 E501 line too long (80 > 79 characters)

reviewbotreviewbot

Col: 80 E501 line too long (83 > 79 characters)

reviewbotreviewbot

Col: 80 E501 line too long (80 > 79 characters)

reviewbotreviewbot

Col: 80 E501 line too long (81 > 79 characters)

reviewbotreviewbot

I feel we should just keep this as RBTools. That way it's very clear, when they see the URLs, and …

chipx86chipx86

resource's

chipx86chipx86

Wrong number of ===s.

chipx86chipx86

Missing period.

chipx86chipx86

Here too. And others.

chipx86chipx86

Same question about the cookies.

chipx86chipx86

Missing a trailing period.

chipx86chipx86

Col: 80 E501 line too long (80 > 79 characters)

reviewbotreviewbot

Col: 80 E501 line too long (82 > 79 characters)

reviewbotreviewbot

Col: 11 E401 multiple imports on one line

reviewbotreviewbot

Col: 80 E501 line too long (80 > 79 characters)

reviewbotreviewbot

Col: 80 E501 line too long (83 > 79 characters)

reviewbotreviewbot

Col: 80 E501 line too long (80 > 79 characters)

reviewbotreviewbot

Col: 80 E501 line too long (81 > 79 characters)

reviewbotreviewbot

Same goes for here (The RBTools bit).

chipx86chipx86

Are we instantiating the API? We're using API a lot in this paragraph - maybe we should say, "Here is …

mike_conleymike_conley

Maybe we could show an example here?

mike_conleymike_conley

For clarity's sake, maybe we should call this review_request, to disambiguate between review requests and WebAPI HTTP requests.

mike_conleymike_conley

"for use" -> "to use"

mike_conleymike_conley
SM
david
  1. I didn't look at any of the build system stuff yet, this is just a review of the doc text.
  2. docs/api/tutorial.txt (Diff revision 2)
     
     
    Show all issues
    Might as well have this fit PEP-8. Space after the :
    1. The proper way to make the create call now uses kwargs, so this is a non-issue now.
  3. docs/api/tutorial.txt (Diff revision 2)
     
     
     
     
     
     
     
     
     
     
    Show all issues
    I think it would be easier to read and probably more useful if you showed this loading the diff from a file.
  4. docs/api/tutorial.txt (Diff revision 2)
     
     
     
    Show all issues
    ?
    1. This is just a reminder to link to the resource specific functionality documentation when I've written it. Certain resources have extra helper methods which I need to document.
  5. docs/api/tutorial.txt (Diff revision 2)
     
     
     
     
     
    Show all issues
    Same here re: loading from a file.
  6. docs/api/tutorial.txt (Diff revision 2)
     
     
     
     
     
     
     
     
     
     
     
    Show all issues
    Maybe show what happens if you try to publish and there's no user or group assigned?
    1. Hmm, that poses a bit of a problem since there is a bug in RBs API which will allow you to publish review requests without having reviewers. So, if I show what *should* happen, it will be incorrect documentation.
    2. How about we fix that bug? :)
    3. I'm going to drop this issue for now. I've been looking in to fixing this in RB's Web API, and it's
      proving to be much more work than expected.
      
      I'm going to work on a fix separately and not let this block the release of rbtools 0.5
  7. 
      
SM
reviewbot
  1. This is a review from Review Bot.
      Tool: PEP8 Style Checker
      Processed Files:
        docs/conf.py
      Ignored Files:
        docs/Makefile
        docs/index.txt
        .gitignore
        docs/api/overview.txt
        docs/contents.txt
        docs/api/tutorial.txt
        docs/api/resource-specific.txt
    
    
  2. docs/conf.py (Diff revision 3)
     
     
    Show all issues
    Col: 80
     E501 line too long (80 > 79 characters)
    
  3. docs/conf.py (Diff revision 3)
     
     
    Show all issues
    Col: 80
     E501 line too long (82 > 79 characters)
    
  4. docs/conf.py (Diff revision 3)
     
     
    Show all issues
    Col: 11
     E401 multiple imports on one line
    
  5. docs/conf.py (Diff revision 3)
     
     
    Show all issues
    Col: 80
     E501 line too long (80 > 79 characters)
    
  6. docs/conf.py (Diff revision 3)
     
     
    Show all issues
    Col: 80
     E501 line too long (83 > 79 characters)
    
  7. docs/conf.py (Diff revision 3)
     
     
    Show all issues
    Col: 80
     E501 line too long (80 > 79 characters)
    
  8. docs/conf.py (Diff revision 3)
     
     
    Show all issues
    Col: 80
     E501 line too long (81 > 79 characters)
    
  9. 
      
david
  1. The pages themselves look pretty good, but I'm worried that just calling it "rbtools documentation" will get a lot of hits from people looking for docs on how to use rbtools. Can we call these "code base documentation" like we do for reviewboard?
    1. So, my intention was to have both sets be part of the same
      documentation. All of the API client stuff under "api", and
      the commands stuff under another folder etc.
      
      The commands stuff is coming next, I just wrote this stuff
      first.
  2. 
      
chipx86
  1. 
      
  2. docs/api/overview.txt (Diff revision 3)
     
     
    Does this reference work?
    1. Yeah, the configuration is set up to check for references
      in the review board documentation as well, so all these
      webapi2.0 references are hooked up.
  3. docs/api/overview.txt (Diff revision 3)
     
     
     
    Show all issues
    Maybe just link "hyperlinks" to this?
  4. docs/api/overview.txt (Diff revision 3)
     
     
    Show all issues
    Technically, all the keys in this would be quoted, since they do that in JSON.
  5. docs/api/overview.txt (Diff revision 3)
     
     
    Show all issues
    Got an extra space in here.
  6. docs/api/overview.txt (Diff revision 3)
     
     
    Show all issues
    "keyword"
  7. docs/api/overview.txt (Diff revision 3)
     
     
    Show all issues
    field's
  8. docs/api/overview.txt (Diff revision 3)
     
     
    Show all issues
    resource's ?
  9. docs/api/overview.txt (Diff revision 3)
     
     
    Show all issues
    administrator's
  10. docs/api/overview.txt (Diff revision 3)
     
     
    Show all issues
    Capitalize "Specify"
  11. docs/api/resource-specific.txt (Diff revision 3)
     
     
    Show all issues
    Resource-Specific
  12. docs/api/resource-specific.txt (Diff revision 3)
     
     
    Show all issues
    I'd maybe remove "Specific" on these sub-headers.
  13. docs/api/resource-specific.txt (Diff revision 3)
     
     
    Show all issues
    "retrieve"
  14. docs/api/resource-specific.txt (Diff revision 3)
     
     
    Show all issues
    Comma after "examples"
  15. docs/api/resource-specific.txt (Diff revision 3)
     
     
    Show all issues
    "API", for consistency.
  16. docs/api/resource-specific.txt (Diff revision 3)
     
     
    Show all issues
    Comma after ``uri-template``.
  17. docs/api/resource-specific.txt (Diff revision 3)
     
     
    Show all issues
    Comma after ``uri-template``
  18. docs/api/resource-specific.txt (Diff revision 3)
     
     
    Show all issues
    This looks left over from something.
  19. docs/api/tutorial.txt (Diff revision 3)
     
     
    Show all issues
    "Review Board"
  20. docs/api/tutorial.txt (Diff revision 3)
     
     
    Show all issues
    API?
  21. docs/api/tutorial.txt (Diff revision 3)
     
     
     
     
     
     
    Show all issues
    We have the room, so I'd suggest we have the first parameter on the "RBClient(" line.
  22. docs/api/tutorial.txt (Diff revision 3)
     
     
    Show all issues
    "documentation"
  23. docs/api/tutorial.txt (Diff revision 3)
     
     
     
    Show all issues
    I don't think that's true anymore. It should be possible to create a review request with no repository, for file attachments.
    1. You're correct, it will work without a repository now. I'll fix this up.
  24. docs/api/tutorial.txt (Diff revision 3)
     
     
    Show all issues
    "ID"
  25. docs/api/tutorial.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  26. docs/api/tutorial.txt (Diff revision 3)
     
     
    Show all issues
    Refs are going to use the page titles, which may not fit well in the sentence. I'd make sure to check all these (a simple 'make html' should generate readable output), and maybe change some to be like: :ref:`resource-specific functionality <python-api-resource-specific`.
    1. Yeah I've been generating as I've been writing it. This will
      come out as (Links have been surrounded by []):
      
      "This can be accomplished using the resource’s create method,
      but the [Diff List Resource] has [Resource-Specific Functionality]
      to make this task easier".
      
      (Note: I updated the references name without updating its usage,
      so this wasn't working properly, I've fixed it now though).
  27. docs/api/tutorial.txt (Diff revision 3)
     
     
    Show all issues
    resource's
  28. docs/api/tutorial.txt (Diff revision 3)
     
     
    Show all issues
    Comma after "attachment"
  29. docs/api/tutorial.txt (Diff revision 3)
     
     
     
     
     
    Show all issues
    4 space indentation, relative to the code's indentation block.
    1. Ah, nice catch, don't know how I ended up with 5 space :P
  30. docs/api/tutorial.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  31. docs/api/tutorial.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Indentation is wonky.
    1. Very wonky. Again, not sure what I was doing here haha.
  32. docs/api/tutorial.txt (Diff revision 3)
     
     
    Show all issues
    No comma after "group"
  33. docs/api/tutorial.txt (Diff revision 3)
     
     
    Show all issues
    Comma after "requirement"
  34. docs/api/tutorial.txt (Diff revision 3)
     
     
     
    Show all issues
    Odd way to format a paragraph ;)
    1. I don't know what you're talking about, this is how all the
      cool kids are doing it!
  35. docs/api/tutorial.txt (Diff revision 3)
     
     
    Show all issues
    Comma after "review request'
  36. docs/conf.py (Diff revision 3)
     
     
    What do we want to do as far as copyright assignment? Assign it to Review Board? Leave it at you?
    1. I brought this up in IRC. David suggested I put myself as the
      copyright, but I'm fine assigning copyright to "The Review Board
      Project" or something. It's up to you guys.
  37. docs/contents.txt (Diff revision 3)
     
     
    Show all issues
    I feel we should just keep this as RBTools. That way it's very clear, when they see the URLs, and it should help with any Googling.
  38. 
      
SM
reviewbot
  1. This is a review from Review Bot.
      Tool: PEP8 Style Checker
      Processed Files:
        docs/conf.py
      Ignored Files:
        docs/Makefile
        docs/index.txt
        .gitignore
        docs/api/overview.txt
        docs/contents.txt
        docs/api/tutorial.txt
        docs/api/resource-specific.txt
    
    
    1. The Sphinx default config sure upsets ReviewBot, doesn't it? Maybe we should just fix these up... Though that's more just busy work right now.
  2. docs/conf.py (Diff revision 4)
     
     
    Show all issues
    Col: 80
     E501 line too long (80 > 79 characters)
    
  3. docs/conf.py (Diff revision 4)
     
     
    Show all issues
    Col: 80
     E501 line too long (82 > 79 characters)
    
  4. docs/conf.py (Diff revision 4)
     
     
    Show all issues
    Col: 11
     E401 multiple imports on one line
    
  5. docs/conf.py (Diff revision 4)
     
     
    Show all issues
    Col: 80
     E501 line too long (80 > 79 characters)
    
  6. docs/conf.py (Diff revision 4)
     
     
    Show all issues
    Col: 80
     E501 line too long (83 > 79 characters)
    
  7. docs/conf.py (Diff revision 4)
     
     
    Show all issues
    Col: 80
     E501 line too long (80 > 79 characters)
    
  8. docs/conf.py (Diff revision 4)
     
     
    Show all issues
    Col: 80
     E501 line too long (81 > 79 characters)
    
  9. 
      
chipx86
  1. 
      
  2. docs/api/overview.txt (Diff revision 4)
     
     
    Trying to decide if it's a good idea to show cookie_file=. Not sure if we want everyone out there who follows this to start copying/pasting this.
  3. docs/api/overview.txt (Diff revision 4)
     
     
    Show all issues
    resource's
  4. docs/api/resource-specific.txt (Diff revision 4)
     
     
     
    Show all issues
    Wrong number of ===s.
  5. docs/api/resource-specific.txt (Diff revision 4)
     
     
    Show all issues
    Missing period.
  6. docs/api/resource-specific.txt (Diff revision 4)
     
     
     
    Show all issues
    Here too. And others.
  7. docs/api/tutorial.txt (Diff revision 4)
     
     
    Show all issues
    Same question about the cookies.
  8. docs/api/tutorial.txt (Diff revision 4)
     
     
    Show all issues
    Missing a trailing period.
  9. docs/index.txt (Diff revision 4)
     
     
    Show all issues
    Same goes for here (The RBTools bit).
  10. 
      
SM
reviewbot
  1. This is a review from Review Bot.
      Tool: PEP8 Style Checker
      Processed Files:
        docs/conf.py
      Ignored Files:
        docs/Makefile
        docs/index.txt
        .gitignore
        docs/api/overview.txt
        docs/contents.txt
        docs/api/tutorial.txt
        docs/api/resource-specific.txt
    
    
  2. 
      
mike_conley
  1. This is really excellent! Just a few suggestions.
  2. docs/api/overview.txt (Diff revision 5)
     
     
    Show all issues
    Are we instantiating the API? We're using API a lot in this paragraph - maybe we should say, "Here is an example of how to instantiate the client, and retrieve the root resource".
  3. docs/api/overview.txt (Diff revision 5)
     
     
    Show all issues
    Maybe we could show an example here?
  4. docs/api/tutorial.txt (Diff revision 5)
     
     
    Show all issues
    For clarity's sake, maybe we should call this review_request, to disambiguate between review requests and WebAPI HTTP requests.
  5. docs/index.txt (Diff revision 5)
     
     
    Show all issues
    "for use" -> "to use"
  6. 
      
SM
reviewbot
  1. This is a review from Review Bot.
      Tool: PEP8 Style Checker
      Processed Files:
        docs/conf.py
      Ignored Files:
        docs/Makefile
        docs/index.txt
        .gitignore
        docs/api/overview.txt
        docs/contents.txt
        docs/api/tutorial.txt
        docs/api/resource-specific.txt
    
    
  2. 
      
chipx86
  1. Looks good. David still has that open issue that we should figure out though.
  2. 
      
SM
Review request changed
Status:
Completed
Change Summary:
Pushed to master (1d91e7f6b1076992e6248f4f0cb34d7a086cd1ec).