Add a user manual.

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

Information

ReviewBot
master
dd23f61...

Reviewers

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.


Description From Last Updated

Care to upload the images?

brenniebrennie

Something that stood out strongly to me is that information on tools are scattered across too many pages. If I …

chipx86chipx86

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

brenniebrennie

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

brenniebrennie

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

brenniebrennie

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

brenniebrennie

The URL should be https://www.reviewboard.org/docs/manual/latest/ Otherwise we'll have 2 redirects for this.

chipx86chipx86

Can you add a reference anchor for this page, so we'll be able to more easily link to it in …

chipx86chipx86

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

chipx86chipx86

Is two trailing slashes correct?

brenniebrennie

Both "command line" and "command-line" are valid terms, but we should probably standardize on one. Most of our docs say …

chipx86chipx86

Can we link to PMD? If you don't already know what it is, this paragraph is very confusing, and sounds …

chipx86chipx86

Let's link this.

chipx86chipx86

Can we add a reference anchor here too?

chipx86chipx86

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

chipx86chipx86

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

chipx86chipx86

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

chipx86chipx86

Should be httpd, not http. The standard way of working with services these days (I think this has been true …

chipx86chipx86

No need for the backticks on these.

chipx86chipx86

Too many blank lines.

chipx86chipx86

Instead of linking to this, we should add an intersphinx for celery in the Sphinx config file, naming it celery. …

chipx86chipx86

Should be only one blank line. This is also in the wrong section.

chipx86chipx86

We should link this.

chipx86chipx86

Too many blank lines.

chipx86chipx86

Here, too.

chipx86chipx86

Can you add a reference anchor here?

chipx86chipx86

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

chipx86chipx86

No need for backticks. Same with others below.

chipx86chipx86

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

chipx86chipx86

There's 2 spaces here between "and" and "click".

chipx86chipx86

"Celery" ?

chipx86chipx86

No need for backticks.

chipx86chipx86

No need for backticks.

chipx86chipx86

No need for backticks.

chipx86chipx86

Too many blank lines.

chipx86chipx86

No need for backticks.

chipx86chipx86

No need for backticks.

chipx86chipx86

No need for backticks.

chipx86chipx86

Sphinx has a handy way to reference PEPs. You can just do: :pep:`8`

chipx86chipx86

"installed"

chipx86chipx86

No need for backticks.

chipx86chipx86
brennie
  1. 
      
  2. Show all issues

    Care to upload the images?

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

    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)
     
     
    Show all issues

    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)
     
     
     
     
     
     
     
     
     
     
     
     
     
    Show all issues

    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)
     
     
     
    Show all issues

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

    1. Clarified this sentence a bit.

  7. 
      
david
brennie
  1. Ship It!
  2. 
      
chipx86
  1. It'll be nice to have a manual to link to :)

  2. Show all issues

    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)
     
     
    Show all issues

    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)
     
     
     
     
    Show all issues

    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. Show all issues

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

  6. Show all issues

    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. Show all issues

    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. Show all issues

    Let's link this.

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

    Can we add a reference anchor here too?

  10. Show all issues

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

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

    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)
     
     
     
     
     
     
     
     
     
    Show all issues

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

  13. Show all issues

    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)
     
     
     
    Show all issues

    No need for the backticks on these.

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

    Too many blank lines.

  16. Show all issues

    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)
     
     
     
     
     
    Show all issues

    Should be only one blank line.

    This is also in the wrong section.

  18. Show all issues

    We should link this.

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

    Too many blank lines.

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

    Here, too.

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

    Can you add a reference anchor here?

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

    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)
     
     
    Show all issues

    No need for backticks. Same with others below.

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

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

  25. 
      
david
brennie
  1. 
      
  2. docs/reviewbot/reviewbot/configuration.rst (Diff revisions 2 - 3)
     
     
    Show all issues

    Is two trailing slashes correct?

  3. 
      
chipx86
  1. 
      
  2. Show all issues

    There's 2 spaces here between "and" and "click".

  3. Show all issues

    "Celery" ?

  4. Show all issues

    No need for backticks.

  5. Show all issues

    No need for backticks.

  6. Show all issues

    No need for backticks.

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

    Too many blank lines.

  8. Show all issues

    No need for backticks.

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

    No need for backticks.

  10. Show all issues

    No need for backticks.

  11. Show all issues

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

    :pep:`8`
    
  12. Show all issues

    "installed"

  13. Show all issues

    No need for backticks.

  14. 
      
david
chipx86
  1. Ship It!
  2. 
      
david
Review request changed
Status:
Completed
Change Summary:
Pushed to master (c2e6e56)