[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 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,13 @@
 
 .. _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
-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`.
+your patch gets accepted:
 
-- ``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.
+- We recommend using Python 3.8 or higher for development of Pylint as it gives
+  you access to the latest ``ast`` parser.
+- 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.
@@ -42,6 +22,8 @@ of Pylint as it gives you access to the latest ``ast`` parser.
   `What's New` section). For the release document we usually write some more details,
   and it is also a good place to offer examples on how the new change is supposed to work.
 
+- Document your change, if it is a non-trivial one.
+
 - If you used multiple emails or multiple names when contributing, add your mails
   and preferred name in the ``script/.contributors_aliases.json`` file.
 
@@ -51,8 +33,6 @@ of Pylint as it gives you access to the latest ``ast`` parser.
   `Closing issues via commit messages`_ of the GitHub documentation for more
   information on this)
 
-- Document your change, if it is a non-trivial one.
-
 - Send a pull request from GitHub (see `About pull requests`_ for more insight
   about this topic)
 

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,51 @@
-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.
+
+**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
+--------------------
+
+If you're testing new changes in astroid you need to also clone astroid_ and install
+with an editable installation alongside pylint as follows::
 
+    # Suppose you're in the pylint directory
     git clone https://github.com/PyCQA/astroid.git
-    cd astroid
-    python3 -m pip install -e .
+    python3 -m pip install -e astroid/
 
-If you want to check the coverage locally, consider using `pytest-cov`_::
+You're now using the local astroid in pylint and can control the version with git for example::
 
-    python3 -m pip install pytest-cov
+    cd astroid/
+    git switch my-astroid-dev-branch
 
 .. _pytest-cov: https://pypi.org/project/pytest-cov/
 .. _astroid: https://github.com/pycqa/astroid
+.. _git: https://git-scm.com/