add doc8 pre-commits

[giovp]

suggest to add doc8 as pre-commit check.

close #126

[github-actions]

A PR has been generated to the instance repo:
scverse/cookiecutter-scverse-instance#30

You can check out the PR to preview your changes
in an instance of the cookiecutter template. The PR will be kept in sync with
this PR automatically.

[Zethson]

@giovp we're mostly using markdown right? Why do we need doc8? For the eval_rst sections? Not for the translated stuff right?

[giovp]

yeah but most importantly for docstrings

[Zethson]

If it's about docstrings, does it detect which docstring style is used? If not, do we need to configure this?

[giovp]

I don't think so, I believe it's basic styles

[grst]

Why do we even need this?

What is checked:
    - invalid RST format - D000
    - lines should not be longer than 79 characters - D001
      - RST exception: line with no whitespace except in the beginning
      - RST exception: lines with http or https urls
      - RST exception: literal blocks
      - RST exception: rst target directives
    - no trailing whitespace - D002
    - no tabulation for indentation - D003
    - no carriage returns (use unix newlines) - D004
    - no newline at end of file - D005

I think most of this is autofixed by prettier.
And in general I'm not a big fan of adding more checks that complain but do not fix

[Zethson]

I agree with @grst , especially the prettier part. Do you insist @giovp or is it OK if we close this PR?

[giovp]

I don't remember what but I literally had a docstrings which was fixed by pre-commit on a generated repo with this template. I don't think prettier checks rst directive, it's more about formatting.
I don't have strong feeling and fine to close it, but it's really useful in my experience. For instance even rst directive like bulletpoints I always get confused with the indentations. it's easier to actually build the doc later with doc8 active.

[grst]

So it's only about

    - invalid RST format - D000

So if we add this, I would make it ignore all other codes to avoid potential conflicts with prettier or other checks.

By default it also only checks .rst files, which we don't use in this template anyway. I'm not sure what it would do with myst files, if were told it to check .md files as well.

[giovp]

mmh I think all of them. Like training whitespaces is also in docstrings. Myst is for docs but docstrings would still be in rst right?

[giovp]

no chance this is getting through? can also close, not super strong feelings, think useful but ok to close and delete.

[giovp]

e.g. #154 from @adamgayoso broke doc8

Scanning...
Validating...
docs/_templates/autosummary/class.rst:15: D000 Explicit markup ends without a blank line; unexpected unindent.
docs/_templates/autosummary/class.rst:17: D000 Definition list ends without a blank line; unexpected unindent.
docs/_templates/autosummary/class.rst:27: D000 Explicit markup ends without a blank line; unexpected unindent.
docs/_templates/autosummary/class.rst:31: D000 Definition list ends without a blank line; unexpected unindent.
docs/_templates/autosummary/class.rst:43: D000 Explicit markup ends without a blank line; unexpected unindent.
docs/_templates/autosummary/class.rst:57: D000 Explicit markup ends without a blank line; unexpected unindent.
========
Total files scanned = 1
Total files ignored = 0
Total accumulated errors = 6
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 = 6

fix is very straightforward, just need to add some blank lines here and there, see https://github.com/scverse/spatialdata/blob/main/docs/_templates/autosummary/class.rst

also understands that it is not actually useful in any way. Am actually gonna close this for now.