added info for getting compilation output from meson on autorebuild

added force MSVC to troubleshooting
added meson-python to intersphinx

Co-authored-by: Kyle Sunden <[email protected]>
Co-authored-by: Elliott Sales de Andrade <[email protected]>

Author: 3 people

doc/conf.py

@@ -207,6 +207,7 @@ 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)
 }
 
 

doc/devel/development_setup.rst

@@ -164,12 +164,25 @@ command ::
 
 The 'editable/develop mode' builds everything and places links in your Python environment
 so that Python will be able to import Matplotlib from your development source directory.
-This allows you to import your modified version of Matplotlib without re-installing after
-every change. Note that before the merging of the `Meson port
-<https://github.com/matplotlib/matplotlib/pull/26621>`_, this is only true for ``*.py``
-files. If you change the C-extension source based on a commit before the change to the
-Meson build system (which might also happen if you change branches), you will have to
-re-run the above command.
+This allows you to import your modified version of Matplotlib without having to
+re-install after changing a ``.py`` or compiled extension file.
+
+When working on a branch that does not have Meson enabled, meaning it does not
+have :ghpull:`26621` in its history (log), you will have to reinstall from source
+each time you change any compiled extension code.
+
+Build options
+-------------
+If you are working heavily with files that need to be compiled, you may want to
+inspect the compilation log. This can be enabled by setting the environment
+variable :envvar:`MESONPY_EDITABLE_VERBOSE` or by setting the ``editable-verbose``
+config during installation ::
+
+   python -m pip install --no-build-isolation --config-settings=editable-verbose=true --editable .
+
+For more information on installation and other configuration options, see the
+Meson Python :external+meson-python:ref:`editable installs guide <how-to-guides-editable-installs>`.
+
 
 Verify the Installation
 =======================

doc/devel/troubleshooting.rst

@@ -43,3 +43,23 @@ unlink this file. Multiple versions of Matplotlib can be linked to the same DLL,
 for example a development version installed in a development conda environment
 and a stable version running in a Jupyter notebook. To resolve this error, fully
 close all running instances of Matplotlib.
+
+Windows compilation errors
+==========================
+If the compiled extensions are not building on Windows due to errors in linking to
+Windows' header files, for example ``../../src/_tkagg.cpp:133:10: error: 'WM_DPICHANGED' was not declared in this scope``,
+you should check which compiler Meson is using:
+
+.. code-block:: bat
+
+    Build type: native build
+    Project name: matplotlib
+    Project version: 3.9.0.dev0
+    C compiler for the host machine: cc (gcc 7.2.0 "cc (Rev1, Built by MSYS2 project) 7.2.0")
+    C linker for the host machine: cc ld.bfd 2.29.1
+    C++ compiler for the host machine: c++ (gcc 7.2.0 "c++ (Rev1, Built by MSYS2 project) 7.2.0")
+    C++ linker for the host machine: c++ ld.bfd 2.29.1
+
+Our :ref:`dependencies <dependencies>` documentation lists the minimum header
+version if you intended to use ``MSYS2``. If you intended to use ``MSVC`` then
+you may need to force Meson to :external+meson-python:ref:`use MSVC <vsenv-example>`.

pyproject.toml

@@ -287,4 +287,7 @@ ignore_messages = [
     "Hyperlink target \".*\" is not referenced.",
     "Duplicate implicit target name: \".*\".",
     "Duplicate explicit target name: \".*\".",
+    # sphinx.ext.intersphinx directives
+    "No role entry for \"external+.*\".",
+    "Unknown interpreted text role \"external+.*\"."
 ]