Documentation: Consolidate zap/codegen

cecille · Oct 23, 2024 · 256889f · 256889f
1 parent c02c070
commit 256889f
Show file tree

Hide file tree

Showing 14 changed files with 40 additions and 8 deletions.
diff --git a/docs/cluster_and_device_type_dev/cluster_and_device_type_dev.md b/docs/cluster_and_device_type_dev/cluster_and_device_type_dev.md
@@ -48,11 +48,11 @@ Note that the output should also be verified against the spec using the
 -   Goal: get zap to understand the new cluster so it can be used on devices
     (XML and glue)
 
-![](../getting_started/img/zap_compiler.png)
+![](../zap_and_codegen/img/zap_compiler.png)
 
 ### Cluster definitions and ZAP
 
-Please see [ZAP](../getting_started/zap.md) for an introduction to ZAP.
+Please see [ZAP](../zap_and_codegen/zap_intro.md) for an introduction to ZAP.
 
 After implementing the changes outlined in the wiki article, your cluster and
 device type should show up in zap. you can check this by running zaptool with
@@ -64,17 +64,17 @@ To ensure the cluster and device type are correctly implemented for ZAP, open
 the endpoint configuration and ensure the device type appears in the device type
 list.
 
-![](../getting_started/img/zap3.png)
+![](../zap_and_codegen/img/zap3.png)
 
 Next, check your cluster. The "domain" parameter in the XML controls which group
 the cluster is in. It should have all the expected attributes, commands and
 events.
 
-![](../getting_started/img/zap4.png)
+![](../zap_and_codegen/img/zap4.png)
 
 Last, ensure that your attributes have the storage option set appropriately.
 
-![](../getting_started/img/zap5.png)
+![](../zap_and_codegen/img/zap5.png)
 
 ### Cluster implementation - Ember and overrides
 

diff --git a/docs/getting_started/first_example.md b/docs/getting_started/first_example.md
@@ -121,3 +121,23 @@ where:
 -   on is the attribute name
 -   0x12344321 is the node ID you used for commissioning
 -   1 is the endpoint
+
+## Making changes to the example app composition
+
+Most of the examples use a static definition of the device composition. This
+composition is defined in a .zap file, that is intended to be read and managed
+through the ZAP tool. Example apps most commonly store their zap configuration
+files in a -common subdirectory which is shared across all the platform
+implementations.
+
+The basic steps involved in making changes to example apps are as follows:
+
+-   Open the .zap file in the zap tool and make the required changes
+-   Run generate.py to generate the .matter file from the .zap file
+-   Re-build the application to incorporate the changes
+-   Run device composition tests to ensure the new composition is spec compliant
+
+Information on updating with ZAP can be found in
+[Updating an application ZAP file](../zap_and_codegen/code_generation.md#flow-for-updating-an-application-zap-file).
+
+Information on testing can be found in [Testing](../testing/index.md).
diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md
@@ -12,5 +12,4 @@ The following docs are a brief introduction to SDK development.
 ```
 
 -   [Running your first example](./first_example.md)
--   [SDK Basics](./SDKBasics.md)
--   [ZAP](./zap.md)
+-   [SDK Architecture Basics](./SDKBasics.md)
diff --git a/docs/index.md b/docs/index.md
@@ -18,8 +18,8 @@ product_considerations/index
 testing/index
 tips_and_troubleshooting/index
 tools/index
+zap_and_codegen/index
 BUG_REPORT
-code_generation
 upgrading
 
 ```

diff --git a/docs/code_generation.md → docs/zap_and_codegen/code_generation.md b/docs/code_generation.md → docs/zap_and_codegen/code_generation.md
@@ -197,6 +197,11 @@ via `-o/--output-dir`.
 ./scripts/tools/zap/generate.py $PATH_TO_ZAP_FILE
 ```
 
+Rebuild the application.
+
+It is also recommended to run device composition tests to ensure the selected
+composition is spec compliant (see [Testing](../testing/index.md))
+
 ### Compile-time code generation / pre-generated code
 
 A subset of code generation (both `codegen.py` and `zap-cli`) is done at compile

diff --git a/docs/getting_started/img/zap1.png → docs/zap_and_codegen/img/zap1.png b/docs/getting_started/img/zap1.png → docs/zap_and_codegen/img/zap1.png
diff --git a/docs/getting_started/img/zap2.png → docs/zap_and_codegen/img/zap2.png b/docs/getting_started/img/zap2.png → docs/zap_and_codegen/img/zap2.png
diff --git a/docs/getting_started/img/zap3.png → docs/zap_and_codegen/img/zap3.png b/docs/getting_started/img/zap3.png → docs/zap_and_codegen/img/zap3.png
diff --git a/docs/getting_started/img/zap4.png → docs/zap_and_codegen/img/zap4.png b/docs/getting_started/img/zap4.png → docs/zap_and_codegen/img/zap4.png
diff --git a/docs/getting_started/img/zap5.png → docs/zap_and_codegen/img/zap5.png b/docs/getting_started/img/zap5.png → docs/zap_and_codegen/img/zap5.png
diff --git a/docs/getting_started/img/zap6.png → docs/zap_and_codegen/img/zap6.png b/docs/getting_started/img/zap6.png → docs/zap_and_codegen/img/zap6.png
diff --git a/docs/getting_started/img/zap_compiler.png → docs/zap_and_codegen/img/zap_compiler.png b/docs/getting_started/img/zap_compiler.png → docs/zap_and_codegen/img/zap_compiler.png
diff --git a/docs/zap_and_codegen/index.md b/docs/zap_and_codegen/index.md
@@ -0,0 +1,8 @@
+# ZAP and Codegen
+
+```{toctree}
+:glob:
+:maxdepth: 1
+
+*
+```
diff --git a/docs/getting_started/zap.md → docs/zap_and_codegen/zap_intro.md b/docs/getting_started/zap.md → docs/zap_and_codegen/zap_intro.md