From b25200a9aa707d2f0cb623663539cce576511a52 Mon Sep 17 00:00:00 2001 From: C Freeman Date: Mon, 28 Oct 2024 23:10:00 -0400 Subject: [PATCH] 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 * 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 Co-authored-by: Jeff Bumgardner --- .github/workflows/zap_templates.yaml | 2 +- .restyled.yaml | 4 +-- .spellcheck.yml | 2 +- .../cluster_and_device_type_dev.md | 10 ++++---- docs/getting_started/changing_examples.md | 24 ++++++++++++++---- docs/getting_started/first_example.md | 2 +- docs/getting_started/index.md | 2 -- docs/guides/simulated_device_linux.md | 4 +-- docs/{ => ids_and_codes}/ERROR_CODES.md | 0 docs/ids_and_codes/index.md | 10 ++++++++ docs/{ => ids_and_codes}/spec_clusters.md | 0 docs/{ => ids_and_codes}/zap_clusters.md | 0 docs/index.md | 7 ++--- docs/{ => zap_and_codegen}/code_generation.md | 5 ++++ .../img/zap1.png | Bin .../img/zap2.png | Bin .../img/zap3.png | Bin .../img/zap4.png | Bin .../img/zap5.png | Bin .../img/zap6.png | Bin .../img/zap_compiler.png | Bin docs/zap_and_codegen/index.md | 8 ++++++ .../zap.md => zap_and_codegen/zap_intro.md} | 0 scripts/tools/zap_regen_all.py | 2 +- 24 files changed, 56 insertions(+), 26 deletions(-) rename docs/{ => ids_and_codes}/ERROR_CODES.md (100%) create mode 100644 docs/ids_and_codes/index.md rename docs/{ => ids_and_codes}/spec_clusters.md (100%) rename docs/{ => ids_and_codes}/zap_clusters.md (100%) rename docs/{ => zap_and_codegen}/code_generation.md (98%) rename docs/{getting_started => zap_and_codegen}/img/zap1.png (100%) rename docs/{getting_started => zap_and_codegen}/img/zap2.png (100%) rename docs/{getting_started => zap_and_codegen}/img/zap3.png (100%) rename docs/{getting_started => zap_and_codegen}/img/zap4.png (100%) rename docs/{getting_started => zap_and_codegen}/img/zap5.png (100%) rename docs/{getting_started => zap_and_codegen}/img/zap6.png (100%) rename docs/{getting_started => zap_and_codegen}/img/zap_compiler.png (100%) create mode 100644 docs/zap_and_codegen/index.md rename docs/{getting_started/zap.md => zap_and_codegen/zap_intro.md} (100%) diff --git a/.github/workflows/zap_templates.yaml b/.github/workflows/zap_templates.yaml index 717f8ca95628fa..383a98583bd9fc 100644 --- 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 index c201729d30e41a..446dad740b96a5 100644 --- 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 index 757034586b9bd0..36461334c881ee 100644 --- 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 index a19336a5939b73..ad509ea57a418b 100644 --- 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 index 611610ce43fb59..02ba357d861300 100644 --- 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 index d75d9e7b1a4fee..7b005f3adc63db 100644 --- 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 index 1bfbe3f57cc333..fc8b9bd1713085 100644 --- 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 index db7e6bc4ef55ad..eb4d6d7564c0c6 100644 --- 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 b/docs/ids_and_codes/ERROR_CODES.md similarity index 100% rename from docs/ERROR_CODES.md rename to docs/ids_and_codes/ERROR_CODES.md diff --git a/docs/ids_and_codes/index.md b/docs/ids_and_codes/index.md new file mode 100644 index 00000000000000..ef87b9ca01c569 --- /dev/null +++ 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 b/docs/ids_and_codes/spec_clusters.md similarity index 100% rename from docs/spec_clusters.md rename to docs/ids_and_codes/spec_clusters.md diff --git a/docs/zap_clusters.md b/docs/ids_and_codes/zap_clusters.md similarity index 100% rename from docs/zap_clusters.md rename to docs/ids_and_codes/zap_clusters.md diff --git a/docs/index.md b/docs/index.md index 89e4661e2a0e1e..cd5fe17d102fd4 100644 --- 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 b/docs/zap_and_codegen/code_generation.md similarity index 98% rename from docs/code_generation.md rename to docs/zap_and_codegen/code_generation.md index bf5b6f3036963a..e6ff51b3182e77 100644 --- a/docs/code_generation.md +++ b/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 b/docs/zap_and_codegen/img/zap1.png similarity index 100% rename from docs/getting_started/img/zap1.png rename to docs/zap_and_codegen/img/zap1.png diff --git a/docs/getting_started/img/zap2.png b/docs/zap_and_codegen/img/zap2.png similarity index 100% rename from docs/getting_started/img/zap2.png rename to docs/zap_and_codegen/img/zap2.png diff --git a/docs/getting_started/img/zap3.png b/docs/zap_and_codegen/img/zap3.png similarity index 100% rename from docs/getting_started/img/zap3.png rename to docs/zap_and_codegen/img/zap3.png diff --git a/docs/getting_started/img/zap4.png b/docs/zap_and_codegen/img/zap4.png similarity index 100% rename from docs/getting_started/img/zap4.png rename to docs/zap_and_codegen/img/zap4.png diff --git a/docs/getting_started/img/zap5.png b/docs/zap_and_codegen/img/zap5.png similarity index 100% rename from docs/getting_started/img/zap5.png rename to docs/zap_and_codegen/img/zap5.png diff --git a/docs/getting_started/img/zap6.png b/docs/zap_and_codegen/img/zap6.png similarity index 100% rename from docs/getting_started/img/zap6.png rename to docs/zap_and_codegen/img/zap6.png diff --git a/docs/getting_started/img/zap_compiler.png b/docs/zap_and_codegen/img/zap_compiler.png similarity index 100% rename from docs/getting_started/img/zap_compiler.png rename to docs/zap_and_codegen/img/zap_compiler.png diff --git a/docs/zap_and_codegen/index.md b/docs/zap_and_codegen/index.md new file mode 100644 index 00000000000000..7301f03b2147d7 --- /dev/null +++ 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 b/docs/zap_and_codegen/zap_intro.md similarity index 100% rename from docs/getting_started/zap.md rename to docs/zap_and_codegen/zap_intro.md diff --git a/scripts/tools/zap_regen_all.py b/scripts/tools/zap_regen_all.py index afe931fd8609a6..0284e9eff9dd93 100755 --- 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