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)
     
     

    Single quotes.

  3. 
      
misery
chipx86
  1. 
      
  2. 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)
     
     

    "will not be listed"

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

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

    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)
     
     
     

    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)
     
     

    "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)
     
     

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

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

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

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

    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)
     
     

    No blank line here.

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

    Add a blank line here.

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

    Can get rid of the backticks around doc8 here.

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

    Please capitalize the first letter of each of these.

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

    Please capitalize the first letter of each of these.

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

    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: Closed (submitted)

Change Summary:

Pushed to master (ff05573)
Loading...