DOC: clarify no-build-isolation & mypy ignoring new functions (matplotlib#28282)

Author: story645

doc/conf.py

@@ -236,7 +236,8 @@ def _check_dependencies():
     'scipy': ('https://docs.scipy.org/doc/scipy/', None),
     'tornado': ('https://www.tornadoweb.org/en/stable/', None),
     'xarray': ('https://docs.xarray.dev/en/stable/', None),
-    'meson-python': ('https://meson-python.readthedocs.io/en/stable/', None)
+    'meson-python': ('https://meson-python.readthedocs.io/en/stable/', None),
+    'pip': ('https://pip.pypa.io/en/stable/', None),
 }
 
 

doc/devel/coding_guide.rst

@@ -89,8 +89,12 @@ We generally use `stub files
 the type information for ``colors.py``. A notable exception is ``pyplot.py``,
 which is type hinted inline.
 
-Type hints are checked by the mypy :ref:`pre-commit hook <pre-commit-hooks>`,
-can often be verified by running ``tox -e stubtest``.
+Type hints can be validated by the `stubtest
+<https://mypy.readthedocs.io/en/stable/stubtest.html>`_ tool, which can be run
+locally using ``tox -e stubtest`` and is a part of the :ref:`automated-tests`
+suite. Type hints for existing functions are also checked by the mypy
+:ref:`pre-commit hook <pre-commit-hooks>`.
+
 
 New modules and files: installation
 ===================================

doc/devel/development_setup.rst

@@ -254,3 +254,9 @@ listed in ``.pre-commit-config.yaml``, against the full codebase with ::
 To run a particular hook manually, run ``pre-commit run`` with the hook id ::
 
     pre-commit run <hook id> --all-files
+
+
+Please note that the ``mypy`` pre-commit hook cannot check the :ref:`type-hints`
+for new functions; instead the stubs for new functions are checked using the
+``stubtest`` :ref:`CI check <automated-tests>` and can be checked locally using
+``tox -e stubtest``.

doc/install/dependencies.rst

@@ -222,14 +222,13 @@ Build dependencies
 Python
 ------
 
-By default, ``pip`` will build packages using build isolation, meaning that these
-build dependencies are temporally installed by pip for the duration of the
-Matplotlib build process. However, build isolation is disabled when :ref:`installing Matplotlib for development <development-install>`;
-therefore we recommend using one of our :ref:`virtual environment configurations <dev-environment>` to
-create a development environment in which these packages are automatically installed.
-
-If you are developing Matplotlib and unable to use our environment configurations,
-then you must manually install the following packages into your development environment:
+``pip`` normally builds packages using :external+pip:doc:`build isolation <reference/build-system/pyproject-toml>`,
+which means that ``pip`` installs the dependencies listed here for the
+duration of the build process. However, build isolation is disabled via the the
+:external+pip:ref:`--no-build-isolation <install_--no-build-isolation>` flag
+when :ref:`installing Matplotlib for development <development-install>`, which
+means that the dependencies must be explicitly installed, either by :ref:`creating a virtual environment <dev-environment>`
+(recommended) or by manually installing the following packages:
 
 - `meson-python <https://meson-python.readthedocs.io/>`_ (>= 0.13.1).
 - `ninja <https://ninja-build.org/>`_ (>= 1.8.2). This may be available in your package