pw_build: Update docs summary
This change adapts Pigweed's build system introductory summary into its
ReST documentation.
Change-Id: Icabdca3049a58285207fa177263aefc46be13960
diff --git a/pw_build/docs.rst b/pw_build/docs.rst
index 7057946..cf92341 100644
--- a/pw_build/docs.rst
+++ b/pw_build/docs.rst
@@ -1,20 +1,33 @@
-.. _chapter-build:
-
.. default-domain:: cpp
.. highlight:: sh
+.. _chapter-build:
+
--------
pw_build
--------
-The build module contains the configuration necessary to build Pigweed using
-`GN`_/`Ninja`_, `CMake`_/`Ninja`_, or `Bazel`_.
+Pigweed's modules aim to be easily integratable into both new and existing
+embedded projects. To that goal, the ``pw_build`` module provides support for
+multiple build systems. Our personal favorite is `GN`_/`Ninja`_, which is used
+by upstream developers for its speed and flexibility. `CMake`_ and `Bazel`_
+build files are also provided by all modules, allowing Pigweed to be added to a
+project with minimal effort.
.. _GN: https://gn.googlesource.com/gn/
-.. _CMake: https://cmake.org/
.. _Ninja: https://ninja-build.org/
+.. _CMake: https://cmake.org/
.. _Bazel: https://bazel.build/
+Beyond just compiling code, Pigweed’s GN build system can also:
+
+* Generate HTML documentation, via our Sphinx integration (with ``pw_docgen``)
+* Display memory usage report cards (with pw_bloat)
+* Incrementally run unit tests after code changes (with ``pw_target_runner``)
+* And more!
+
+These are only supported in the GN build, so we recommend using it if possible.
+
GN / Ninja
==========
The common configuration for GN for all modules is in the ``BUILD.gn`` file.