DOC: add docs on using the build-dir config setting

Closes gh-540

Also touches on gh-246, which is a common enough hiccup that it's
useful to explicitly show dealing with `meson-log.txt` in CI.

Author: rgommers

docs/how-to-guides/config-settings.rst

@@ -19,7 +19,7 @@ the ``-C`` short command line option:
 
 .. tab-set::
 
-    .. tab-item:: pypa/buid
+    .. tab-item:: pypa/build
         :sync: key_pypa_build
 
 	.. code-block:: console
@@ -59,3 +59,60 @@ immediately install it, replace ``wheel`` with ``install``.  See the
 
 .. _build: https://pypa-build.readthedocs.io/en/stable/
 .. _pip: https://pip.pypa.io/
+
+
+Using a persistent build directory
+==================================
+
+By default, ``meson-python`` creates a temporary build directory, which is
+deleted when the build terminates. The ``build-dir``
+:ref:`config setting <reference-config-settings>` can be used to build in a
+user-specified build directory which will not be deleted instead. For example:
+
+.. tab-set::
+
+    .. tab-item:: pypa/build
+        :sync: key_pypa_build
+
+	.. code-block:: console
+
+	   $ python -m build -Cbuild-dir=build
+
+    .. tab-item:: pip
+        :sync: key_pip
+
+	.. code-block:: console
+
+	   $ python -m pip install . -Cbuild-dir=build
+
+
+The ``build`` directory will now contain all the build artifacts and support
+files created by ``meson``, ``ninja`` and ``meson-python``. This may be useful
+for a couple of reasons:
+
+- For development efficiency (incremental builds)
+- For accessing build logs and intermediate build outputs when debugging
+
+The same build directory can be used by subsequent invocations of
+``meson-python``. This avoids having to rebuild the whole project when testing
+changes during development. This will work with any config settings flags,
+including for cross compilation.
+
+Using ``build-dir`` makes it possible to access Meson's log and introspection
+files.  To diagnose why a build fails at the project configuration stage, it is
+sometimes necessary to inspect the detailed Meson log in the
+``meson-logs/meson-log.txt`` file in the build directory. The complete path to
+the log file is available in the command output when the build fails. For
+example, when dependency detection fails it is often necessary to look
+at the detailed output of ``pkg-config`` or other dependency detection methods
+to understand why the detection failed. This is particularly common in CI
+setups - it can be helpful to show more detailed log files when the build step
+of a CI build fails, for example in a GitHub Actions workflow file:
+
+.. code-block:: yaml
+
+    - name: Build the package
+      run: python -m build --wheel -Cbuild-dir=build
+    - name: Show meson-log.txt
+      if: failure()  # or `always()`, if output is not too long
+      run: cat build/meson-logs/meson-log.txt

docs/reference/config-settings.rst

@@ -23,10 +23,6 @@ them.
    exists and contains a valid Meson build directory setup, the
    project will be reconfigured using ``meson setup --reconfigure``.
 
-   The same build directory can be used by subsequent invocations of
-   ``meson-python``. This avoids having to rebuild the whole project
-   when testing changes during development.
-
    For backward compatibility reasons, the alternative ``builddir``
    spelling is also accepted.