[doc] Add a CI check for the doc being properly generated

And cleanup the doc about dev installation for contributors.

Author: Pierre-Sassoulas

.github/workflows/checks.yaml

@@ -189,4 +189,5 @@ jobs:
         run: |
           . venv/bin/activate
           cd doc
-          make html
+          pre-commit run --hook-stage push sphinx-generated-doc --all-files||echo "Make sure that there \
+          are no modification locally when launching 'make html'"&&exit 1

.pre-commit-config.yaml

@@ -74,6 +74,13 @@ repos:
         args: ["-rn", "-sn", "--rcfile=pylintrc", "--fail-on=I", "--spelling-dict=en"]
         exclude: tests/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: fix-documentation
         name: Fix documentation
         entry: python3 -m script.fix_documentation

doc/development_guide/contributor_guide/contribute.rst

@@ -6,33 +6,12 @@
 
 .. _repository:
 
-Repository
-----------
-
-Pylint is developed using the git_ distributed version control system.
-
-You can clone Pylint and its dependencies from ::
-
-  git clone https://github.com/PyCQA/pylint
-  git clone https://github.com/PyCQA/astroid
-
-.. _git: https://git-scm.com/
-
 Got a change for Pylint?  Below are a few steps you should take to make sure
-your patch gets accepted. We recommend using Python 3.8 or higher for development
+your patch gets accepted.  We recommend using Python 3.8 or higher for development
 of Pylint as it gives you access to the latest ``ast`` parser.
 
-- Test your code
-
-  For more information on how to use our test suite and write new tests see :ref:`testing`.
-
-- ``pylint`` uses black_ and isort_ among other Python auto-formatters.
-  We have a pre-commit hook which should take care of the autoformatting for
-  you. To enable it, do the following:
-
-    * install ``pre-commit`` using ``pip install pre-commit``
-
-    * then run ``pre-commit install`` in the ``pylint`` root directory to enable the git hooks.
+- Install the dev dependencies, see :ref:`contributor_install`.
+- Use our test suite and write new tests, see :ref:`contributor_testing`.
 
 - Add a short entry to the change log describing the change, except for internal
   implementation only changes.

doc/development_guide/contributor_guide/tests/index.rst

@@ -1,11 +1,10 @@
-.. _testing:
-
-=======
-Testing
-=======
-
+.. _contributor_testing:
 .. _test_your_code:
 
+==============
+Testing pylint
+==============
+
 Pylint is very well tested and has a high code coverage. New contributions are not accepted
 unless they include tests.
 

doc/development_guide/contributor_guide/tests/install.rst

@@ -1,25 +1,44 @@
-Installation
-============
+.. _contributor_install:
+
+Contributor installation
+========================
+
+Basic installation
+------------------
+
+Pylint is developed using the git_ distributed version control system.
+
+You can clone Pylint using ::
+
+  git clone https://github.com/PyCQA/pylint
 
 Before you start testing your code, you need to install your source-code package locally.
-Suppose you have cloned pylint into a directory, say ``my-pylint``.
-To set up your environment for testing, open a terminal and run::
+Suppose you just cloned pylint with the previous ``git clone`` command. To set up your
+environment for testing, open a terminal and run::
 
-    cd my-pylint
+    cd pylint
+    python3 -m venv venv
+    source venv/bin/activate
     pip install -r requirements_test_min.txt
 
 This ensures your testing environment is similar to Pylint's testing environment on GitHub.
 
-If you're testing new changes in astroid you need to clone astroid_ and install
-with an editable installation as follows::
+**Optionally** (Because there's an auto-fix if you open a merge request): We have pre-commit hooks which should take
+care of the autoformatting for you before each commits. To enable it, run ``pre-commit install`` in the ``pylint``
+root directory.
 
-    git clone https://github.com/PyCQA/astroid.git
-    cd astroid
-    python3 -m pip install -e .
+**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.
 
-If you want to check the coverage locally, consider using `pytest-cov`_::
+Astroid installation
+--------------------
 
-    python3 -m pip install pytest-cov
+If you're testing new changes in astroid you need to also clone astroid_ and install
+with an editable installation as follows::
+
+    git clone https://github.com/PyCQA/astroid.git
+    python3 -m pip install -e astroid/
 
 .. _pytest-cov: https://pypi.org/project/pytest-cov/
 .. _astroid: https://github.com/pycqa/astroid
+.. _git: https://git-scm.com/