pw_dumb_io: Update docs
Add/update docs for the pw_dumb_io facade and backends. Configures GN
build files such that all the backend docs are built even if the backend
isn't in use.
Change-Id: I91fca1cb2d3f5d4b57ae1f6991a89270a35be1c6
diff --git a/pw_dumb_io_baremetal_stm32f429/BUILD.gn b/pw_dumb_io_baremetal_stm32f429/BUILD.gn
index fe7fb55..6240129 100644
--- a/pw_dumb_io_baremetal_stm32f429/BUILD.gn
+++ b/pw_dumb_io_baremetal_stm32f429/BUILD.gn
@@ -12,30 +12,42 @@
# License for the specific language governing permissions and limitations under
# the License.
-config("linker_script_config") {
- _linker_script = "stm32f429.ld"
- inputs = [
- _linker_script,
- ]
- ldflags = [ "-T" + rebase_path("$_linker_script") ]
+import("$dir_pw_docgen/docs.gni")
+
+# This if statement allows docs to always build even if the target isn't
+# compatible with this backend.
+if (dir_pw_dumb_io_backend == dir_pw_dumb_io_baremetal_stm32f429) {
+ config("linker_script_config") {
+ _linker_script = "stm32f429.ld"
+ inputs = [
+ _linker_script,
+ ]
+ ldflags = [ "-T" + rebase_path("$_linker_script") ]
+ }
+
+ source_set("linker_script") {
+ public_configs = [ ":linker_script_config" ]
+ }
+
+ source_set("pw_dumb_io_baremetal_stm32f429") {
+ public_configs = [ "$dir_pw_build:pw_default_cpp" ]
+ public_deps = [
+ ":linker_script",
+ ]
+ deps = [
+ "$dir_pw_dumb_io:default_putget_bytes",
+ "$dir_pw_dumb_io:facade",
+ "$dir_pw_preprocessor",
+ ]
+ sources = [
+ "core_init.c",
+ "dumb_io_baremetal.cc",
+ ]
+ }
}
-source_set("linker_script") {
- public_configs = [ ":linker_script_config" ]
-}
-
-source_set("pw_dumb_io_baremetal_stm32f429") {
- public_configs = [ "$dir_pw_build:pw_default_cpp" ]
- public_deps = [
- ":linker_script",
- ]
- deps = [
- "$dir_pw_dumb_io:default_putget_bytes",
- "$dir_pw_dumb_io:facade",
- "$dir_pw_preprocessor",
- ]
+pw_doc_group("docs") {
sources = [
- "core_init.c",
- "dumb_io_baremetal.cc",
+ "docs.rst",
]
}
diff --git a/pw_dumb_io_baremetal_stm32f429/docs.rst b/pw_dumb_io_baremetal_stm32f429/docs.rst
index 5385e90..423f69e 100644
--- a/pw_dumb_io_baremetal_stm32f429/docs.rst
+++ b/pw_dumb_io_baremetal_stm32f429/docs.rst
@@ -1,18 +1,22 @@
-.. _chapter-dumb-io-baremetal-stm32f429:
+.. _chapter-pw-dumb-io-baremetal-stm32f429:
.. default-domain:: cpp
.. highlight:: sh
----------------------------
-STM32F429 baremetal dumb IO
----------------------------
+------------------------------
+pw_dumb_io_baremetal_stm32f429
+------------------------------
+
+``pw_dumb_io_baremetal_stm32f429`` implements the ``pw_dumb_io`` facade over
+UART.
+
The STM32F429 baremetal dumb IO backend provides device startup code and a UART
-driver to layer that allows applications built against the ``pw_dumb_io``
-interface to run on a STM32F429 chip and do simple input/output via UART.
-The code is optimized for the STM32F429I-DISC1, using USART1 (which is connected
-to the virtual COM port on the embedded ST-LINKv2 chip). However, this should
-work with all STM32F429 variations (and even some STM32F4xx chips).
+driver layer that allows applications built against the ``pw_dumb_io`` interface
+to run on a STM32F429 chip and do simple input/output via UART. The code is
+optimized for the STM32F429I-DISC1, using USART1 (which is connected to the
+virtual COM port on the embedded ST-LINKv2 chip). However, this should work with
+all STM32F429 variations (and even some STM32F4xx chips).
This backend has no configuration options. The point of it is to provide bare-
minimum platform code needed to do UART reads/writes.
@@ -22,7 +26,7 @@
This module requires relatively minimal setup:
1. Write code against the ``pw_dumb_io`` facade.
- 2. Specify the ``dir_pw_dumb_io_backend`` GN gloabal variable to point to this
+ 2. Specify the ``dir_pw_dumb_io_backend`` GN global variable to point to this
backend.
3. Build an executable with a main() function using a toolchain that
supports Cortex-M4.
