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,63 @@ 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`` will create a temporary build directory, which
+gets cleaned up after the sdist or wheel has been built, or if the build fails.
+The ``build-dir`` config seting (see :ref:`reference-config-settings`) can be
+used to build in a user-specified build directory 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 output 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. The one thing to keep in mind is that changing
+the version of ``meson`` or ``meson-python`` in the build environment between
+separate builds in the same build directory is not supported (it often works,
+but may fail - and the error message cannot be guaranteed to be clear about the
+reason).
+
+Using ``build-dir`` makes it possible to access the log files that Meson
+creates. When a build fails, Meson's CLI logging will display the reason for
+the failure in most cases. However, it is sometimes necessary to look at more
+detailed logs like ``meson-logs/meson-log.txt``. A common reason for this is
+when Meson's 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.