Maybe add doc8?

[ZryletTC]

Thinking doc8 could be useful for checking our static .rst files. Thoughts?

-   repo: https://github.com/PyCQA/doc8
    rev: 0.8.1rc3
    hooks:
    - id: doc8

[ZLLentz]

I'm in favor of .rst standards

[klauer]

Have any sample output to share from one of our projects? Seems good in principle.

[ZryletTC]

Here's a purposefully failed output from pcdshub.github.io. Still trying to figure out why it seems to split the files into two chunks (4 and 3).

(dev) PC92005:pcdshub.github.io pennebak$ pre-commit run --all-files
Don't commit to branch...................................................Passed
Trim Trailing Whitespace.................................................Passed
Fix End of Files.........................................................Passed
Check python ast.........................................................Passed
Check for case conflicts.................................................Passed
Check JSON...........................................(no files to check)Skipped
Check for merge conflicts................................................Passed
Check for broken symlinks............................(no files to check)Skipped
Check Xml............................................(no files to check)Skipped
Check Yaml...............................................................Passed
doc8.....................................................................Passed
(dev) PC92005:pcdshub.github.io pennebak$ pre-commit run --all-files
Don't commit to branch...................................................Passed
Trim Trailing Whitespace.................................................Passed
Fix End of Files.........................................................Passed
Check python ast.........................................................Passed
Check for case conflicts.................................................Passed
Check JSON...........................................(no files to check)Skipped
Check for merge conflicts................................................Passed
Check for broken symlinks............................(no files to check)Skipped
Check Xml............................................(no files to check)Skipped
Check Yaml...............................................................Passed
doc8.....................................................................Failed
- hook id: doc8
- exit code: 1

Scanning...
Validating...
source/overview.rst:8: D001 Line too long
========
Total files scanned = 4
Total files ignored = 0
Total accumulated errors = 1
Detailed error counts:
    - doc8.checks.CheckCarriageReturn = 0
    - doc8.checks.CheckIndentationNoTab = 0
    - doc8.checks.CheckMaxLineLength = 1
    - doc8.checks.CheckNewlineEndOfFile = 0
    - doc8.checks.CheckTrailingWhitespace = 0
    - doc8.checks.CheckValidity = 0
Scanning...
Validating...
========
Total files scanned = 3
Total files ignored = 0
Total accumulated errors = 0
Detailed error counts:
    - doc8.checks.CheckCarriageReturn = 0
    - doc8.checks.CheckIndentationNoTab = 0
    - doc8.checks.CheckMaxLineLength = 0
    - doc8.checks.CheckNewlineEndOfFile = 0
    - doc8.checks.CheckTrailingWhitespace = 0
    - doc8.checks.CheckValidity = 0

[klauer]

That looks pretty good. Maybe lowering the verbosity would be a good default?

[ZryletTC]

Yeah good idea. Here's with the --quiet arg

doc8.....................................................................Failed
- hook id: doc8
- exit code: 1

source/overview.rst:8: D001 Line too long

much shorter/cleaner 👍

[klauer]

So much better!

Looks like the three of us agree it'd be a good thing overall - so go for it.