Documentation: more handbook re-org (#36208)

* Documentation: gather IDs and codes into dir * Documentation: Consolidate zap/codegen * Update docs/getting_started/changing_examples.md Co-authored-by: Jeff Bumgardner <[email protected]> * Fix a couple of missed doc refs * Fix some paths for the CI checkers * Not sure why it's not finding this on the CI * fix zap output directory --------- Co-authored-by: Andrei Litvin <[email protected]> Co-authored-by: Jeff Bumgardner <[email protected]>
project-chip · Nov 22, 2024 · 1e6f847 · 1e6f847
1 parent 635045a
commit 1e6f847
Show file tree

Hide file tree

Showing 24 changed files with 56 additions and 26 deletions.
diff --git a/.github/workflows/zap_templates.yaml b/.github/workflows/zap_templates.yaml
@@ -62,7 +62,7 @@ jobs:
             - name: Generate all
               run: ./scripts/run_in_build_env.sh scripts/tools/zap_regen_all.py
             - name: Generate script-maintained items (ERROR_CODES.md)
-              run: ./scripts/run_in_build_env.sh "scripts/error_table.py > docs/ERROR_CODES.md"
+              run: ./scripts/run_in_build_env.sh "scripts/error_table.py > docs/ids_and_codes/ERROR_CODES.md"
             - name: Ensure git works in current working directory
               run: git config --global --add safe.directory `pwd`
             - name: Check for uncommited changes

diff --git a/.restyled.yaml b/.restyled.yaml
@@ -83,9 +83,7 @@ exclude:
     - "scripts/setup/bootstrap.sh" # tries to quote loop variable
     - "integrations/docker/build-all.sh" # tries to quote loop variable
     - "scripts/setup/pigweed.json" # TODO(#29547). This file is temporary copy from pigweed repo that has minor edits. No restyle help in diff.
-    - "docs/ERROR_CODES.md" # generated by scripts, not easy to align tables
-    - "docs/zap_clusters.md" # generated by scripts, not easy to align tables
-    - "docs/spec_clusters.md" # generated by scripts, not easy to align tables
+    - "docs/ids_and_codes/**" # generated by scripts, not easy to align tables
     - "docs/testing/yaml_pseudocluster.md" # generated by scripts, restyler makes the tables render improperly
     - "docs/testing/yaml_schema.md" # generated by scripts, restyler makes the tables render improperly
 

diff --git a/.spellcheck.yml b/.spellcheck.yml
@@ -65,7 +65,7 @@ matrix:
       # converts markdown to HTML
       - pyspelling.filters.markdown:
     sources:
-      - '**/*.md|!third_party/**|!examples/common/**/repo/**|!docs/ERROR_CODES.md|!docs/clusters.md|!docs/testing/yaml_schema.md|!docs/testing/yaml_pseudocluster.md|!docs/testing/python.md|!docs/testing/ChipDeviceCtrlAPI.md|!docs/issue_triage.md'
+      - '**/*.md|!third_party/**|!examples/common/**/repo/**|!docs/ids_and_codes/ERROR_CODES.md|!docs/clusters.md|!docs/testing/yaml_schema.md|!docs/testing/yaml_pseudocluster.md|!docs/testing/python.md|!docs/testing/ChipDeviceCtrlAPI.md|!docs/issue_triage.md'
     aspell:
       ignore-case: true
       camel-case: true
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/changing_examples.md b/docs/getting_started/changing_examples.md
@@ -4,10 +4,10 @@ The composition of most examples in the SDK is static and code generated.
 
 The tool used to describe and change the composition of an example is called
 ZAP. More information about ZAP and a walk-through of the tool can be found in
-the [ZAP introduction](./zap.md). The composition of the device is captured in a
-.zap file, which is readable by the ZAP tool. This is then compiled into a
-human-readable .matter file, which is used to build the static features of the
-example.
+the [ZAP introduction](../zap_and_codegen/zap_intro.md). The composition of the
+device is captured in a .zap file, which is readable by the ZAP tool. This is
+then compiled into a human-readable .matter file, which is used to build the
+static features of the example.
 
 To change the composition of a device example, you need to
 
@@ -35,7 +35,8 @@ This will open the ZAP GUI tool, which can be used to change the endpoint
 composition, clusters, features, attributes, commands and events exposed by the
 device.
 
-Details of how to use the tool can be found in the [ZAP Introduction](./zap.md).
+Details of how to use the tool can be found in the
+[ZAP Introduction](../zap_and_codegen/zap_intro.md).
 
 ## Running code generation
 
@@ -62,3 +63,16 @@ recompile the .zap files for all the examples and the controller.
 
 After generating the .matter file, re-build the example. Instructions for
 building examples are given in [Building your first example](./first_example.md)
+
+## Ensuring device conformance
+
+After changing the examples, it is important to ensure they remain spec
+compliant. Although there are numerous certification tests to check the various
+parts of the device, the tests most likely to be affected by changes to ZAP are
+the conformance tests, which ensure that the device included meets the
+conformance requirements for clusters and device types. To run conformance tests
+against the example app, see [Testing](../testing/index.md). The tests that
+ensure the device composition is spec compliant are found in
+[Device Basic Composition Test](../../src/python_testing/TC_DeviceBasicComposition.py)
+and
+[Device Conformance Tests](../../src/python_testing/TC_DeviceConformance.py).
diff --git a/docs/getting_started/first_example.md b/docs/getting_started/first_example.md
@@ -37,7 +37,7 @@ for testing. More information about the python controller can be found in the
 
 The examples directory contains a set of apps using an example device
 composition \.zap file. For more information about device composition and zap,
-see [ZAP documentation](./zap.md).
+see [ZAP documentation](../zap_and_codegen/zap_intro.md).
 
 This quick start guide will walk you through
 

diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md
@@ -10,11 +10,9 @@ The following docs are a brief introduction to SDK development.
 first_example
 changing_examples
 SDKBasics
-zap
 
 ```
 
 -   [Running your first example](./first_example.md)
 -   [Changing examples](./changing_examples.md)
 -   [SDK Architecture Overview](./SDKBasics.md)
--   [ZAP Introduction](./zap.md)
diff --git a/docs/guides/simulated_device_linux.md b/docs/guides/simulated_device_linux.md
@@ -19,8 +19,8 @@ is defined by a ZAP config file and tests can be added with a
 
 -   [Building Prerequisites](./BUILDING.md#prerequisites)
 -   [Prepare For Building](./BUILDING.md#prepare-for-building)
--   [Code Generate](../code_generation.md)
--   [ZAP Installed](../code_generation.md#installing-zap-and-environment-variables)
+-   [Code Generate](../zap_and_codegen/code_generation.md)
+-   [ZAP Installed](../zap_and_codegen/code_generation.md#installing-zap-and-environment-variables)
 
 ## Building the default Simulated App with Script
 

diff --git a/docs/ERROR_CODES.md → docs/ids_and_codes/ERROR_CODES.md b/docs/ERROR_CODES.md → docs/ids_and_codes/ERROR_CODES.md
diff --git a/docs/ids_and_codes/index.md b/docs/ids_and_codes/index.md
@@ -0,0 +1,10 @@
+# IDs and Codes
+
+
+```{toctree}
+:glob:
+:maxdepth: 1
+
+*
+
+```
diff --git a/docs/spec_clusters.md → docs/ids_and_codes/spec_clusters.md b/docs/spec_clusters.md → docs/ids_and_codes/spec_clusters.md
diff --git a/docs/zap_clusters.md → docs/ids_and_codes/zap_clusters.md b/docs/zap_clusters.md → docs/ids_and_codes/zap_clusters.md
diff --git a/docs/index.md b/docs/index.md
@@ -10,6 +10,7 @@ VSCODE_DEVELOPMENT
 ci-cd/index
 development_controllers/index
 getting_started/index
+ids_and_codes/index
 cluster_and_device_type_dev/index
 guides/index
 platforms/index
@@ -19,14 +20,10 @@ product_considerations/index
 testing/index
 tips_and_troubleshooting/index
 tools/index
+zap_and_codegen/index
 BUG_REPORT
-code_generation
-zap_clusters
-spec_clusters
 upgrading
-ERROR_CODES
 issue_triage
-
 ```
 
 ```{include} README.md

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))
+
 ### 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
diff --git a/scripts/tools/zap_regen_all.py b/scripts/tools/zap_regen_all.py
@@ -414,7 +414,7 @@ def getCodegenTemplates():
     targets.append(JinjaCodegenTarget(
         generator="summary-markdown",
         idl_path="src/controller/data_model/controller-clusters.matter",
-        output_directory="docs"))
+        output_directory="docs/ids_and_codes"))
 
     return targets