From 8996f30b580bf7e38408626d11fdf2b0124d6bcf Mon Sep 17 00:00:00 2001
From: Bryce Mecum <petridish@gmail.com>
Date: Thu, 8 Feb 2024 12:14:02 -0900
Subject: [PATCH] Add sphinx-lint

- Adds sphinx-lint to archery as archer lint --docs
- Adds archery lint --docs to pre-commit hook
- Adds sphinx-lint to appropriate setup.py, conda lock, and requirements.txt
---
 .pre-commit-config.yaml           |  6 ++++
 ci/conda_env_sphinx.txt           |  1 +
 dev/archery/archery/cli.py        |  6 ++--
 dev/archery/archery/utils/lint.py | 52 +++++++++++++++++++++++++++++--
 dev/archery/setup.py              |  2 +-
 docs/requirements.txt             |  1 +
 6 files changed, 63 insertions(+), 5 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index d3c7624f63e71..303f59858d92a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -36,6 +36,12 @@ repos:
          - dockerfile
         entry: --entrypoint /bin/hadolint hadolint/hadolint:latest -
         exclude: ^dev/.*$
+      - id: sphinx-lint
+        name: Sphinx Lint
+        entry: archery lint --docs
+        language: system
+        files: ^docs/
+
   - repo: https://github.com/pycqa/flake8
     rev: 6.1.0
     hooks:
diff --git a/ci/conda_env_sphinx.txt b/ci/conda_env_sphinx.txt
index 0e50875fc1ef8..3de38cf63d4e6 100644
--- a/ci/conda_env_sphinx.txt
+++ b/ci/conda_env_sphinx.txt
@@ -24,6 +24,7 @@ pydata-sphinx-theme=0.14
 sphinx-autobuild
 sphinx-design
 sphinx-copybutton
+sphinx-lint
 sphinxcontrib-jquery
 sphinx==6.2
 # Requirement for doctest-cython
diff --git a/dev/archery/archery/cli.py b/dev/archery/archery/cli.py
index 0ad3eee14d1f3..b607dcbbe6c9d 100644
--- a/dev/archery/archery/cli.py
+++ b/dev/archery/archery/cli.py
@@ -260,6 +260,7 @@ def build(ctx, src, build_dir, force, targets, **kwargs):
               "Check all sources files for license texts via Apache RAT."),
     LintCheck('r', "Lint R files."),
     LintCheck('docker', "Lint Dockerfiles with hadolint."),
+    LintCheck('docs', "Lint docs with sphinx-lint."),
 ]
 
 
@@ -284,9 +285,10 @@ def decorate_lint_command(cmd):
               help="Run IWYU on all C++ files if enabled")
 @click.option("-a", "--all", is_flag=True, default=False,
               help="Enable all checks.")
+@click.argument("path", required=False)
 @decorate_lint_command
 @click.pass_context
-def lint(ctx, src, fix, iwyu_all, **checks):
+def lint(ctx, src, fix, iwyu_all, path, **checks):
     if checks.pop('all'):
         # "--all" is given => enable all non-selected checks
         for k, v in checks.items():
@@ -296,7 +298,7 @@ def lint(ctx, src, fix, iwyu_all, **checks):
         raise click.UsageError(
             "Need to enable at least one lint check (try --help)")
     try:
-        linter(src, fix, iwyu_all=iwyu_all, **checks)
+        linter(src, fix, iwyu_all=iwyu_all, path=path, **checks)
     except LintValidationException:
         sys.exit(1)
 
diff --git a/dev/archery/archery/utils/lint.py b/dev/archery/archery/utils/lint.py
index 3efe5994055db..345b56c89b34b 100644
--- a/dev/archery/archery/utils/lint.py
+++ b/dev/archery/archery/utils/lint.py
@@ -435,10 +435,55 @@ def docker_linter(src):
                                                    cwd=src.path))
 
 
-def linter(src, fix=False, *, clang_format=False, cpplint=False,
+class SphinxLint(Command):
+    def __init__(self, src, path=None, sphinx_lint_bin=None, disable=None, enable=None):
+        self.src = src
+        self.path = path
+        self.bin = default_bin(sphinx_lint_bin, "sphinx-lint")
+        self.disable = disable or "all"
+        self.enable = enable
+
+    def lint(self, *args, check=False):
+        docs_path = os.path.join(self.src.path, "docs")
+
+        args = []
+
+        if self.disable:
+            args.extend(["--disable", self.disable])
+
+        if self.enable:
+            args.extend(["--enable", self.enable])
+
+        if self.path is not None:
+            args.extend([self.path])
+        else:
+            args.extend([docs_path])
+
+        return self.run(*args, check=check)
+
+
+def docs_linter(src, path=None):
+    """Run sphinx-lint on docs."""
+    logger.info("Running docs linter (sphinx-lint)")
+
+    sphinx_lint = SphinxLint(
+        src,
+        path=path,
+        disable="all",
+        enable="trailing-whitespace,missing-final-newline"
+    )
+
+    if not sphinx_lint.available:
+        logger.error("sphinx-lint linter requested but sphinx-lint binary not found")
+        return
+
+    yield LintResult.from_cmd(sphinx_lint.lint())
+
+
+def linter(src, fix=False, path=None, *, clang_format=False, cpplint=False,
            clang_tidy=False, iwyu=False, iwyu_all=False,
            python=False, numpydoc=False, cmake_format=False, rat=False,
-           r=False, docker=False):
+           r=False, docker=False, docs=False):
     """Run all linters."""
     with tmpdir(prefix="arrow-lint-") as root:
         build_dir = os.path.join(root, "cpp-build")
@@ -480,6 +525,9 @@ def linter(src, fix=False, *, clang_format=False, cpplint=False,
         if docker:
             results.extend(docker_linter(src))
 
+        if docs:
+            results.extend(docs_linter(src, path))
+
         # Raise error if one linter failed, ensuring calling code can exit with
         # non-zero.
         for result in results:
diff --git a/dev/archery/setup.py b/dev/archery/setup.py
index 2ecc72e04e8aa..e108ce5066df6 100755
--- a/dev/archery/setup.py
+++ b/dev/archery/setup.py
@@ -37,7 +37,7 @@
     'integration': ['cffi'],
     'integration-java': ['jpype1'],
     'lint': ['numpydoc==1.1.0', 'autopep8', 'flake8==6.1.0', 'cython-lint',
-             'cmake_format==0.6.13'],
+             'cmake_format==0.6.13', 'sphinx-lint==0.9.1'],
     'numpydoc': ['numpydoc==1.1.0'],
     'release': ['pygithub', jinja_req, 'jira', 'semver', 'gitpython'],
 }
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 5d6fec7ddf72e..033f3eeb04139 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -9,5 +9,6 @@ pydata-sphinx-theme~=0.14
 sphinx-autobuild
 sphinx-design
 sphinx-copybutton
+sphinx-lint
 sphinx==6.2
 pandas