Add a user manual.

Review Request #8876 - Created April 5, 2017 and submitted

David Trowbridge
ReviewBot
master
dd23f61...
reviewbot

This change adds in a new user manual for Review Bot, which goes into much more
detail about installation, configuration, and what tools are available.

Built HTML and proofread the results.

Loading file attachments...

  • 0
  • 0
  • 40
  • 1
  • 41
Description From Last Updated
Barret Rennie
  1. 
      
  2. Care to upload the images?

  3. docs/reviewbot/_ext/retina_images.py (Diff revision 1)
     
     

    This is in beanbag-docutils as beanbag_docutils.sphinx.ext.retina_images. We should prefer that over this.

  4. docs/reviewbot/conf.py (Diff revision 1)
     
     

    This happened to me too. Looks like its expanding \titleref to a TAB and itleref. Silly Sphinx.

  5. docs/reviewbot/reviewbot/configuration.rst (Diff revision 1)
     
     
     
     
     
     
     
     
     
     
     
     
     

    Aren't code blocks in reST supposed to line up with the c in code-block?

  6. docs/reviewbot/reviewbot/installation.rst (Diff revision 1)
     
     
     

    We don't actually supply the message broker, do we? Isn't that RabbitMQ, etc?

    1. Clarified this sentence a bit.

  7. 
      
David Trowbridge
Barret Rennie
  1. Ship It!
  2. 
      
Christian Hammond
  1. It'll be nice to have a manual to link to :)

  2. Something that stood out strongly to me is that information on tools are scattered across too many pages. If I want to know how to install PMD, I go one place. If I want to know how to configure it, I go somewhere else. If I want to learn more about what it is, a third place.

    I think instead, we should take the approach that repositories/hosting services now have in the Review Board docs. We should make reviewbot/tools/ a directory and have clang.rst, pmd.rst, etc. in there. These should be complete documents on installing, configuring, and using these tools. That way it's really easy to see all the information needed about each tool without navigating different pages. As we expand our supported tools, this will help keep things far more manageable.

  3. docs/reviewbot/conf.py (Diff revision 2)
     
     

    The URL should be https://www.reviewboard.org/docs/manual/latest/

    Otherwise we'll have 2 redirects for this.

  4. docs/reviewbot/reviewbot/configuration.rst (Diff revision 2)
     
     
     
     

    Can you add a reference anchor for this page, so we'll be able to more easily link to it in the future? I've found it really helps to always have one of these for each page.

  5. Maybe provide an example of what this would look like if running locally.

  6. Both "command line" and "command-line" are valid terms, but we should probably standardize on one. Most of our docs say "command line," but some say "command-line." I did some searches to see which is more popular out there, and it seems it's "command line". It's also far more common in search terms:

    https://trends.google.com/trends/explore?q=%22command-line%22,%22command%20line%22

    It seems that Apple and newer Microsoft docs are using "command line" over "command-line" as well. I wish I could find some good info on best practices here from these companies.

  7. Can we link to PMD? If you don't already know what it is, this paragraph is very confusing, and sounds like a requirement for Review Bot. We should have a brief summary of what PMD is before going into configuration for it.

  8. Let's link this.

  9. docs/reviewbot/reviewbot/installation.rst (Diff revision 2)
     
     
     
     

    Can we add a reference anchor here too?

  10. Let's just go ahead and link to this file on GitHub.

  11. docs/reviewbot/reviewbot/installation.rst (Diff revision 2)
     
     
     

    Can we say "the Review Bot extension for Review Board" instead? I had to read this a couple times before I parsed it right.

  12. docs/reviewbot/reviewbot/installation.rst (Diff revision 2)
     
     
     
     
     
     
     
     
     

    Inconsistencies with the number of blank lines here (and below, wiht .. image).

  13. Should be httpd, not http.

    The standard way of working with services these days (I think this has been true for a few years now) is sudo service httpd reload.

  14. docs/reviewbot/reviewbot/installation.rst (Diff revision 2)
     
     
     

    No need for the backticks on these.

  15. docs/reviewbot/reviewbot/installation.rst (Diff revision 2)
     
     
     
     
     
     

    Too many blank lines.

  16. Instead of linking to this, we should add an intersphinx for celery in the Sphinx config file, naming it celery. Then we can do:

    Celery's `supported brokers <celery:brokers>`_
    

    above.

  17. docs/reviewbot/reviewbot/installation.rst (Diff revision 2)
     
     
     
     
     

    Should be only one blank line.

    This is also in the wrong section.

  18. We should link this.

  19. docs/reviewbot/reviewbot/installation.rst (Diff revision 2)
     
     
     
     
     

    Too many blank lines.

  20. docs/reviewbot/reviewbot/installation.rst (Diff revision 2)
     
     
     
     
     

    Here, too.

  21. docs/reviewbot/reviewbot/tools.rst (Diff revision 2)
     
     
     
     

    Can you add a reference anchor here?

  22. docs/reviewbot/reviewbot/tools.rst (Diff revision 2)
     
     

    We should use "current" instead of "latest". They use "latest" as in "bleeding edge," not "current release."

  23. docs/reviewbot/reviewbot/tools.rst (Diff revision 2)
     
     

    No need for backticks. Same with others below.

  24. docs/reviewbot/reviewbot/tools.rst (Diff revision 2)
     
     

    No backticks. They're never needed on .. lines.

  25. 
      
David Trowbridge
Barret Rennie
  1. 
      
  2. docs/reviewbot/reviewbot/configuration.rst (Diff revisions 2 - 3)
     
     

    Is two trailing slashes correct?

  3. 
      
Christian Hammond
  1. 
      
  2. There's 2 spaces here between "and" and "click".

  3. "Celery" ?

  4. No need for backticks.

  5. No need for backticks.

  6. No need for backticks.

  7. docs/reviewbot/reviewbot/tools/cpplint.rst (Diff revision 3)
     
     
     
     
     
     

    Too many blank lines.

  8. No need for backticks.

  9. docs/reviewbot/reviewbot/tools/pmd.rst (Diff revision 3)
     
     

    No need for backticks.

  10. No need for backticks.

  11. Sphinx has a handy way to reference PEPs. You can just do:

    :pep:`8`
    
  12. No need for backticks.

  13. 
      
David Trowbridge
Christian Hammond
  1. Ship It!
  2. 
      
David Trowbridge
Review request changed

Status: Closed (submitted)

Change Summary:

Pushed to master (c2e6e56)
Loading...