[doc] Add a CI check for the doc being properly generated (#6736)

And cleanup the doc about dev installation for contributors.

Co-authored-by: Jacob Walls <[email protected]>

Author: Pierre-Sassoulas

.github/workflows/checks.yaml

@@ -182,4 +182,8 @@ jobs:
         run: |
           . venv/bin/activate
           cd doc
-          make html
+          pre-commit run --hook-stage push sphinx-generated-doc --all-files || {
+            git diff ; \
+            echo "Make sure that there are no modifications locally when launching 'make html'" ; \
+            exit 1; \
+          }

.pre-commit-config.yaml

@@ -94,6 +94,13 @@ repos:
         args: ["-rn", "-sn", "--rcfile=pylintrc", "--fail-on=I", "--spelling-dict=en"]
         exclude: tests(/\w*)*/functional/|tests/input|tests(/\w*)*data/|doc/
         stages: [manual]
+      - id: sphinx-generated-doc
+        alias: sphinx-generated-doc
+        name: sphinx-generated-doc
+        entry: make -C doc/ html
+        pass_filenames: false
+        language: system
+        stages: [push]
       - id: check-newsfragments
         name: Check newsfragments
         entry: python3 -m script.check_newsfragments

doc/development_guide/contributor_guide/tests/install.rst

@@ -28,6 +28,10 @@ This ensures your testing environment is similar to Pylint's testing environment
 pre-commit hooks which should take care of the autoformatting for you before each
 commit. To enable it, run ``pre-commit install`` in the ``pylint`` root directory.
 
+**Even more optionally**: You can enable slow on push hooks with ``pre-commit install --install-hooks -t pre-push``.
+It will do slow checks like checking that the generated documentation is up to date
+before each push.
+
 Astroid installation
 --------------------