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. 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
brennie
  1. Ship It!
  2. 
      
chipx86
  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
brennie
  1. 
      
  2. docs/reviewbot/reviewbot/configuration.rst (Diff revisions 2 - 3)
     
     

    Is two trailing slashes correct?

  3. 
      
chipx86
  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
chipx86
  1. Ship It!
  2. 
      
david
Review request changed

Status: Closed (submitted)

Change Summary:

Pushed to master (c2e6e56)
Loading...