should we lint our documentation ?

[12rambau]

It was suggested to me this morning by github, I didn't even know it existed. Do you think it would make sense to lint the documentation ?
https://github.com/PyCQA/doc8

I know that @choldgraf is more of a myst personn but there are still plenty of .rst files in our doc.

[choldgraf]

In my opinion, linting is useful when it reduces the cognitive overhead of having to make semi-arbitrary decisions about style/structure, and when it helps avoid obvious problems in how code/text/etc is structured (not stylistic differences but obvious things that should happen but often don't). I don't have strong opinions about whether our rST documentation falls into this category, so I'll trust your / others judgment on whether this would be helpful for the project.

[drammock]

I've tried using doc8 locally through a vscode plugin and it's not great. Constant yellow underlines in my RST pages saying things like "unknown interpreted text role :func:". But maybe for a repo that's mostly not documenting code it would be OK? or maybe doc8 is great and just the vscode plugin is not good? I guess I'd suggest to run doc8 on our codebase and see what its results are; if they look like legitimate things that would be better if we fixed them, then great. If it's lots of false positives like "unknown interpreted text role :func:" then I'd say it's not worth it.

[choldgraf]

@drammock one thing I've found annoying with vscode is that it's extensions often rely on the system python (or whatever you specify) rather than a version of python that is attached to a project in a virtual env, so i always get a lot of errors about packages missing etc. Though maybe that wouldn't be an issue if we run doc8 in the dame environment as this package?

[drammock]

@drammock one thing I've found annoying with vscode is that it's extensions often rely on the system python (or whatever you specify) rather than a version of python that is attached to a project in a virtual env

Yeah, some extensions do that, I agree it's annoying. In the case of doc8 though I should retract what I said before. The extension had support for doc8 but was actually using rstcheck. When I switched it to use doc8 the false alarms went away.

I just tried running doc8 /opt/pydata-sphinx-theme/docs and here's a snippet of the (long) output:

/opt/pydata-sphinx-theme/docs/_build/html/_sources/examples/generated/pandas.DataFrame.groupby.rst:2: D000 Title underline too short.
/opt/pydata-sphinx-theme/docs/_build/html/_sources/examples/generated/pandas.DataFrame.groupby.rst:6: D005 No newline at end of file
/opt/pydata-sphinx-theme/docs/_build/html/_sources/examples/generated/pandas.Series.array.rst:2: D000 Title underline too short.
/opt/pydata-sphinx-theme/docs/_build/html/_sources/examples/generated/pandas.Series.array.rst:6: D005 No newline at end of file
/opt/pydata-sphinx-theme/docs/_build/html/_sources/examples/generated/pandas.DataFrame.drop.rst:2: D000 Title underline too short.
/opt/pydata-sphinx-theme/docs/_build/html/_sources/examples/generated/pandas.DataFrame.drop.rst:6: D005 No newline at end of file
/opt/pydata-sphinx-theme/docs/_build/html/_sources/demo/kitchen-sink/api.rst:2: D000 Explicit markup ends without a blank line; unexpected unindent.
/opt/pydata-sphinx-theme/docs/_build/html/_sources/demo/kitchen-sink/index.rst:2: D000 Explicit markup ends without a blank line; unexpected unindent.
/opt/pydata-sphinx-theme/docs/_build/html/_sources/demo/kitchen-sink/paragraph-markup.rst:260: D000 Unknown target name: "5".
/opt/pydata-sphinx-theme/docs/_build/html/_sources/demo/kitchen-sink/paragraph-markup.rst:274: D000 Unknown target name: "nonexistent".
/opt/pydata-sphinx-theme/docs/_build/html/_sources/demo/kitchen-sink/paragraph-markup.rst:303: D000 Unknown target name: "body elements".
/opt/pydata-sphinx-theme/docs/_build/html/_sources/demo/kitchen-sink/paragraph-markup.rst:315: D000 Unknown target name: "hyperlink reference without a target".
/opt/pydata-sphinx-theme/docs/_build/html/_sources/user_guide/install.rst:49: D000 Cannot analyze code. No Pygments lexer found for "none".

plus LOTS AND LOTS of D001 Line too long

[drammock]

Total files scanned = 136
Total files ignored = 0
Total accumulated errors = 1113
Detailed error counts:
    - doc8.checks.CheckCarriageReturn = 0
    - doc8.checks.CheckIndentationNoTab = 0
    - doc8.checks.CheckMaxLineLength = 1078
    - doc8.checks.CheckNewlineEndOfFile = 12
    - doc8.checks.CheckTrailingWhitespace = 0
    - doc8.checks.CheckValidity = 23

[choldgraf]

Fwiw I am definitely not a fan of "max line length" errors for documentation. I much prefer to follow "1 sentence per line" because I think it makes it much easier to diff in the GitHub interface and helps avoid random line length overflows just because your doing minor edits in a paragraph. For one ref on this see:

https://sembr.org/

[drammock]

Fwiw I am definitely not a fan of "max line length" errors for documentation.

same, if we adopt doc8 let's disable D001

[12rambau]

I've already shown in other issues that I'm simply against any length limit (This is why we have wrappers in the first place and they work great). I was of course planning on silencing D001 ;-)