linting: use 'rstcheck' for ReStructuredText

[jameslamb]

Description

rstcheck is a lightweight linter for ReStructuredText files (https://github.com/rstcheck/rstcheck).

We have a lot of .rst files around RAPIDS (GitHub search).

rstcheck could be useful for catching docs formatting issues that aren't caught by sphinx-build -W.

I (@jameslamb) have been using it in other projects for a few years and have found it to be fast, lightweight, and helpful. It's MIT-licensed and approved for use with RAPIDS already.

Benefits of this work

• improves test coverage of a hard-to-test area (visual appearance of docs, cross-linking in docs)
• helps to standardize docs formatting across RAPIDS

Acceptance Criteria

• rstcheck is used in as many RAPIDS repos as whoever picks this up thinks need it

Approach

Use the pre-commit hook, and skip doxygen directives.

configuration (click me)

.pre-commit-config.yaml

  - repo: https://github.com/rstcheck/rstcheck
    rev: v6.2.5
    hooks:
      - id: rstcheck
        args: ["--config", "pyproject.toml"]
        additional_dependencies:
          - myst-parser>=0.13
          - nbsphinx
          - sphinx>=7.3

pyproject.toml

[tool.rstcheck]
ignore_directives = [
    # rstcheck does not understand 'autosummary' directives
    "autosummary",
    # rstcheck does not understand doxygen directives
    "doxygenenum",
    "doxygenfunction",
    "doxygengroup",
    "doxygennamespace",
    "doxygenstruct",
    "doxygentypedef"
]

Start with https://github.com/rapidsai/cugraph-docs. It has the most .rst and should be a good test of whether we like this tool.

Here's what it reports as of this writing:

$ pre-commit run --all-files rstcheck
rstcheck.................................................................Failed
- hook id: rstcheck
- exit code: 1

docs/cugraph-docs/source/api_docs/cugraph/graph_implementation.rst:8: (INFO/1) Duplicate implicit target name: "graph implementation".
docs/cugraph-docs/source/api_docs/cugraph/link_analysis.rst:27: (INFO/1) Duplicate implicit target name: "single-gpu".
docs/cugraph-docs/source/api_docs/cugraph/link_analysis.rst:34: (INFO/1) Duplicate implicit target name: "multi-gpu".
docs/cugraph-docs/source/api_docs/cugraph/link_prediction.rst:26: (INFO/1) Duplicate implicit target name: "single-gpu".
docs/cugraph-docs/source/api_docs/cugraph/link_prediction.rst:34: (INFO/1) Duplicate implicit target name: "multi-gpu".
docs/cugraph-docs/source/api_docs/cugraph/link_prediction.rst:42: (INFO/1) Duplicate implicit target name: "single-gpu".
docs/cugraph-docs/source/api_docs/cugraph/link_prediction.rst:50: (INFO/1) Duplicate implicit target name: "multi-gpu".
docs/cugraph-docs/source/api_docs/cugraph/link_prediction.rst:59: (INFO/1) Duplicate implicit target name: "single-gpu".
docs/cugraph-docs/source/api_docs/cugraph/link_prediction.rst:67: (INFO/1) Duplicate implicit target name: "multi-gpu".
docs/cugraph-docs/source/api_docs/cugraph/sampling.rst:32: (INFO/1) Duplicate implicit target name: "single-gpu".
docs/cugraph-docs/source/api_docs/cugraph/sampling.rst:39: (INFO/1) Duplicate implicit target name: "multi-gpu".
docs/cugraph-docs/source/api_docs/cugraph_cpp/collect_comm_wrapper_cpp.rst:2: (WARNING/2) Title underline too short.
docs/cugraph-docs/source/index.rst:76: (INFO/1) Duplicate implicit target name: "conda".
docs/cugraph-docs/source/index.rst:76: (INFO/1) Duplicate implicit target name: "docker".
docs/cugraph-docs/source/index.rst:76: (INFO/1) Duplicate implicit target name: "pip".
docs/cugraph-docs/source/nx_cugraph/index.rst:21: (ERROR/3) (python) invalid syntax
docs/cugraph-docs/source/nx_cugraph/supported-algorithms.rst:238: (WARNING/2) Title underline too short.
docs/cugraph-docs/source/tutorials/cugraph_blogs.rst:29: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
docs/cugraph-docs/source/tutorials/cugraph_blogs.rst:29: (ERROR/3) Missing matching underline for section title overline.
docs/cugraph-docs/source/tutorials/cugraph_blogs.rst:36: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
Error! Issues detected.

Notes

N/A