Add review bot tool for doc8

Review Request #9489 — Created Jan. 16, 2018 and submitted

Information

ReviewBot
release-1.0.x

Reviewers

doc8 is a style checker for Sphinx (or other)
RST documentation.

doc8 is like flake8 for reStructuredText.

https://pypi.python.org/pypi/doc8

Uploaded a diff an .rst file as review request as saw that
it added some "errors" of this reStructuredText file.

Uploaded a "clean" .rst file and saw that it did no
add any errors.

Description From Last Updated

Thanks for the contribution! Can you flesh out the description more to talk more about what the tool does and …

chipx86chipx86

Single quotes.

brenniebrennie

"will not be listed"

chipx86chipx86

Can you bullet-proof this a bit, so that if we get some unexpected output, we'll log it and not just …

chipx86chipx86

It'd be nice to flesh this out a bit more, talk about what kind of things this looks for, and …

chipx86chipx86

"used text files" is weird. Maybe "Encoding used for rst files"? This also needs a period at the end.

daviddavid

pass is unnecessary if there's another statement in the block.

daviddavid

Reference here should be DOC8_ (which matches with the URL listed as _DOC8

daviddavid

Reference here should be RST_LINT_ We should also use :command:`doc8` instead of ``doc8``

daviddavid

No blank line here.

daviddavid

Add a blank line here.

daviddavid

Can get rid of the backticks around doc8 here.

daviddavid

Please capitalize the first letter of each of these.

daviddavid

Please capitalize the first letter of each of these.

daviddavid

Like my comment elsewhere, none of the other documents have this, and it doesn't particularly add much value on top …

daviddavid
misery
brennie
  1. One tiny nit. This looks great!

  2. bot/reviewbot/tools/doc8.py (Diff revision 2)
     
     
    Show all issues

    Single quotes.

  3. 
      
misery
chipx86
  1. 
      
  2. Show all issues

    Thanks for the contribution!

    Can you flesh out the description more to talk more about what the tool does and what it's checking for, at a high level?

  3. bot/reviewbot/tools/doc8.py (Diff revision 3)
     
     
    Show all issues

    "will not be listed"

    1. https://reviews.reviewboard.org/r/9500/ :-)

  4. bot/reviewbot/tools/doc8.py (Diff revision 3)
     
     
     
     
     
     
    Show all issues

    Can you bullet-proof this a bit, so that if we get some unexpected output, we'll log it and not just crash?

  5. docs/reviewbot/reviewbot/tools/doc8.rst (Diff revision 3)
     
     
     
    Show all issues

    It'd be nice to flesh this out a bit more, talk about what kind of things this looks for, and also to have a link to the page.

    Should also have a section on configuring the tool.

  6. 
      
misery
david
  1. 
      
  2. bot/reviewbot/tools/doc8.py (Diff revision 4)
     
     
    Show all issues

    "used text files" is weird. Maybe "Encoding used for rst files"?

    This also needs a period at the end.

  3. bot/reviewbot/tools/doc8.py (Diff revision 4)
     
     
    Show all issues

    pass is unnecessary if there's another statement in the block.

  4. docs/reviewbot/reviewbot/tools/doc8.rst (Diff revision 4)
     
     
    Show all issues

    Reference here should be DOC8_ (which matches with the URL listed as _DOC8

  5. docs/reviewbot/reviewbot/tools/doc8.rst (Diff revision 4)
     
     
    Show all issues

    Reference here should be RST_LINT_

    We should also use :command:`doc8` instead of ``doc8``

  6. docs/reviewbot/reviewbot/tools/doc8.rst (Diff revision 4)
     
     
    Show all issues

    No blank line here.

  7. docs/reviewbot/reviewbot/tools/doc8.rst (Diff revision 4)
     
     
    Show all issues

    Add a blank line here.

  8. docs/reviewbot/reviewbot/tools/doc8.rst (Diff revision 4)
     
     
    Show all issues

    Can get rid of the backticks around doc8 here.

  9. docs/reviewbot/reviewbot/tools/doc8.rst (Diff revision 4)
     
     
     
    Show all issues

    Please capitalize the first letter of each of these.

  10. docs/reviewbot/reviewbot/tools/doc8.rst (Diff revision 4)
     
     
     
     
     
    Show all issues

    Please capitalize the first letter of each of these.

  11. docs/reviewbot/reviewbot/tools/doc8.rst (Diff revision 4)
     
     
     
     
     
     
    Show all issues

    Like my comment elsewhere, none of the other documents have this, and it doesn't particularly add much value on top of the UI.

  12. 
      
misery
misery
david
misery
misery
david
  1. Ship It!
  2. 
      
misery
Review request changed
Status:
Re-opened
misery
Review request changed
Status:
Completed
Change Summary:
Pushed to master (ff05573)