Create a short summary of all defined clusters in markdown format (ba…

…sed on controller-clusters) (project-chip#30765) * Start adding a codegen * Implement cluster summary * Add clusters in the markdown index * slight update * Restyle * Prevent restyle.io changing clusters.md * Do not spell check cluster names * Add comment that the file is automatically generated
mkardous-silabs · Dec 1, 2023 · 44ea4eb · 44ea4eb
1 parent e27a453
commit 44ea4eb
Show file tree

Hide file tree

Showing 8 changed files with 189 additions and 1 deletion.
diff --git a/.restyled.yaml b/.restyled.yaml
@@ -85,6 +85,7 @@ exclude:
     - "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/clusters.md" # generated by scripts, not easy to align tables
 
 changed_paths:
     maximum: 100000

diff --git a/.spellcheck.yml b/.spellcheck.yml
@@ -65,6 +65,6 @@ matrix:
       # converts markdown to HTML
       - pyspelling.filters.markdown:
     sources:
-      - '**/*.md|!third_party/**|!examples/common/**/repo/**|!docs/ERROR_CODES.md'
+      - '**/*.md|!third_party/**|!examples/common/**/repo/**|!docs/ERROR_CODES.md|!docs/clusters.md'
     aspell:
       ignore-case: true
diff --git a/docs/clusters.md b/docs/clusters.md
@@ -0,0 +1,124 @@
+<!--
+THIS FILE IS AUTO-GENERATED! DO NOT MODIFY!
+
+Generated from `clusters_markdown.jinja`.
+
+Generally regenerate using one of:
+  - scripts/tools/zap_regen_all.py
+  - ./scripts/codegen.py --output-dir docs --generator summary-markdown src/controller/data_model/controller-clusters.matter
+-->
+
+## List of currently defined clusters
+
+| Code (dec) | Code (hex) | Name                                                    |
+| ---------- | ---------- | ------------------------------------------------------- |
+|          3 |       0x03 | Identify                                                |
+|          4 |       0x04 | Groups                                                  |
+|          5 |       0x05 | Scenes                                                  |
+|          6 |       0x06 | OnOff                                                   |
+|          7 |       0x07 | OnOffSwitchConfiguration                                |
+|          8 |       0x08 | LevelControl                                            |
+|         15 |       0x0F | BinaryInputBasic                                        |
+|         28 |       0x1C | PulseWidthModulation                                    |
+|         29 |       0x1D | Descriptor                                              |
+|         30 |       0x1E | Binding                                                 |
+|         31 |       0x1F | AccessControl                                           |
+|         37 |       0x25 | Actions                                                 |
+|         40 |       0x28 | BasicInformation                                        |
+|         41 |       0x29 | OtaSoftwareUpdateProvider                               |
+|         42 |       0x2A | OtaSoftwareUpdateRequestor                              |
+|         43 |       0x2B | LocalizationConfiguration                               |
+|         44 |       0x2C | TimeFormatLocalization                                  |
+|         45 |       0x2D | UnitLocalization                                        |
+|         46 |       0x2E | PowerSourceConfiguration                                |
+|         47 |       0x2F | PowerSource                                             |
+|         48 |       0x30 | GeneralCommissioning                                    |
+|         49 |       0x31 | NetworkCommissioning                                    |
+|         50 |       0x32 | DiagnosticLogs                                          |
+|         51 |       0x33 | GeneralDiagnostics                                      |
+|         52 |       0x34 | SoftwareDiagnostics                                     |
+|         53 |       0x35 | ThreadNetworkDiagnostics                                |
+|         54 |       0x36 | WiFiNetworkDiagnostics                                  |
+|         55 |       0x37 | EthernetNetworkDiagnostics                              |
+|         56 |       0x38 | TimeSynchronization                                     |
+|         57 |       0x39 | BridgedDeviceBasicInformation                           |
+|         59 |       0x3B | Switch                                                  |
+|         60 |       0x3C | AdministratorCommissioning                              |
+|         62 |       0x3E | OperationalCredentials                                  |
+|         63 |       0x3F | GroupKeyManagement                                      |
+|         64 |       0x40 | FixedLabel                                              |
+|         65 |       0x41 | UserLabel                                               |
+|         66 |       0x42 | ProxyConfiguration                                      |
+|         67 |       0x43 | ProxyDiscovery                                          |
+|         68 |       0x44 | ProxyValid                                              |
+|         69 |       0x45 | BooleanState                                            |
+|         70 |       0x46 | IcdManagement                                           |
+|         71 |       0x47 | Timer                                                   |
+|         72 |       0x48 | OvenCavityOperationalState                              |
+|         73 |       0x49 | OvenMode                                                |
+|         74 |       0x4A | LaundryDryerControls                                    |
+|         80 |       0x50 | ModeSelect                                              |
+|         81 |       0x51 | LaundryWasherMode                                       |
+|         82 |       0x52 | RefrigeratorAndTemperatureControlledCabinetMode         |
+|         83 |       0x53 | LaundryWasherControls                                   |
+|         84 |       0x54 | RvcRunMode                                              |
+|         85 |       0x55 | RvcCleanMode                                            |
+|         86 |       0x56 | TemperatureControl                                      |
+|         87 |       0x57 | RefrigeratorAlarm                                       |
+|         89 |       0x59 | DishwasherMode                                          |
+|         91 |       0x5B | AirQuality                                              |
+|         92 |       0x5C | SmokeCoAlarm                                            |
+|         93 |       0x5D | DishwasherAlarm                                         |
+|         94 |       0x5E | MicrowaveOvenMode                                       |
+|         95 |       0x5F | MicrowaveOvenControl                                    |
+|         96 |       0x60 | OperationalState                                        |
+|         97 |       0x61 | RvcOperationalState                                     |
+|        113 |       0x71 | HepaFilterMonitoring                                    |
+|        114 |       0x72 | ActivatedCarbonFilterMonitoring                         |
+|        128 |       0x80 | BooleanSensorConfiguration                              |
+|        129 |       0x81 | ValveConfigurationAndControl                            |
+|        150 |       0x96 | DemandResponseLoadControl                               |
+|        153 |       0x99 | EnergyEvse                                              |
+|        257 |      0x101 | DoorLock                                                |
+|        258 |      0x102 | WindowCovering                                          |
+|        259 |      0x103 | BarrierControl                                          |
+|        512 |      0x200 | PumpConfigurationAndControl                             |
+|        513 |      0x201 | Thermostat                                              |
+|        514 |      0x202 | FanControl                                              |
+|        516 |      0x204 | ThermostatUserInterfaceConfiguration                    |
+|        768 |      0x300 | ColorControl                                            |
+|        769 |      0x301 | BallastConfiguration                                    |
+|       1024 |      0x400 | IlluminanceMeasurement                                  |
+|       1026 |      0x402 | TemperatureMeasurement                                  |
+|       1027 |      0x403 | PressureMeasurement                                     |
+|       1028 |      0x404 | FlowMeasurement                                         |
+|       1029 |      0x405 | RelativeHumidityMeasurement                             |
+|       1030 |      0x406 | OccupancySensing                                        |
+|       1036 |      0x40C | CarbonMonoxideConcentrationMeasurement                  |
+|       1037 |      0x40D | CarbonDioxideConcentrationMeasurement                   |
+|       1043 |      0x413 | NitrogenDioxideConcentrationMeasurement                 |
+|       1045 |      0x415 | OzoneConcentrationMeasurement                           |
+|       1066 |      0x42A | Pm25ConcentrationMeasurement                            |
+|       1067 |      0x42B | FormaldehydeConcentrationMeasurement                    |
+|       1068 |      0x42C | Pm1ConcentrationMeasurement                             |
+|       1069 |      0x42D | Pm10ConcentrationMeasurement                            |
+|       1070 |      0x42E | TotalVolatileOrganicCompoundsConcentrationMeasurement   |
+|       1071 |      0x42F | RadonConcentrationMeasurement                           |
+|       1283 |      0x503 | WakeOnLan                                               |
+|       1284 |      0x504 | Channel                                                 |
+|       1285 |      0x505 | TargetNavigator                                         |
+|       1286 |      0x506 | MediaPlayback                                           |
+|       1287 |      0x507 | MediaInput                                              |
+|       1288 |      0x508 | LowPower                                                |
+|       1289 |      0x509 | KeypadInput                                             |
+|       1290 |      0x50A | ContentLauncher                                         |
+|       1291 |      0x50B | AudioOutput                                             |
+|       1292 |      0x50C | ApplicationLauncher                                     |
+|       1293 |      0x50D | ApplicationBasic                                        |
+|       1294 |      0x50E | AccountLogin                                            |
+|       1295 |      0x50F | ContentControl                                          |
+|       1296 |      0x510 | ContentAppObserver                                      |
+|       2820 |      0xB04 | ElectricalMeasurement                                   |
+| 4294048773 | 0xFFF1FC05 | UnitTesting                                             |
+| 4294048774 | 0xFFF1FC06 | FaultInjection                                          |
+| 4294048800 | 0xFFF1FC20 | SampleMei                                               |
diff --git a/docs/index.md b/docs/index.md
@@ -17,6 +17,7 @@ examples/index
 tools/index
 BUG_REPORT
 code_generation
+clusters
 ERROR_CODES
 ```
 

diff --git a/scripts/py_matter_idl/matter_idl/generators/markdown/__init__.py b/scripts/py_matter_idl/matter_idl/generators/markdown/__init__.py
@@ -0,0 +1,35 @@
+# Copyright (c) 2023 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+
+from matter_idl.generators import CodeGenerator, GeneratorStorage
+from matter_idl.matter_idl_types import Idl
+
+
+class SummaryMarkdownGenerator(CodeGenerator):
+    """
+    Code generation for markdown files
+    """
+
+    def __init__(self, storage: GeneratorStorage, idl: Idl, **kargs):
+        super().__init__(storage, idl, fs_loader_searchpath=os.path.dirname(__file__))
+
+    def internal_render_all(self):
+        self.internal_render_one_output(
+            template_path="clusters_markdown.jinja",
+            output_file_name="clusters.md",
+            vars={
+                'idl': self.idl,
+            }
+        )
diff --git a/scripts/py_matter_idl/matter_idl/generators/markdown/clusters_markdown.jinja b/scripts/py_matter_idl/matter_idl/generators/markdown/clusters_markdown.jinja
@@ -0,0 +1,17 @@
+<!--
+THIS FILE IS AUTO-GENERATED! DO NOT MODIFY!
+
+Generated from `clusters_markdown.jinja`.
+
+Generally regenerate using one of:
+  - scripts/tools/zap_regen_all.py
+  - ./scripts/codegen.py --output-dir docs --generator summary-markdown src/controller/data_model/controller-clusters.matter
+-->
+
+## List of currently defined clusters
+
+| Code (dec) | Code (hex) | Name                                                    |
+| ---------- | ---------- | ------------------------------------------------------- |
+{%- for cluster in idl.clusters | sort(attribute="code") %}
+| {{ "%10d" | format(cluster.code) }} | {{ ("0x%02X" | format(cluster.code)).rjust(10) }} | {{cluster.name.ljust(55)}} |
+{%- endfor %}
diff --git a/scripts/py_matter_idl/matter_idl/generators/registry.py b/scripts/py_matter_idl/matter_idl/generators/registry.py
@@ -20,6 +20,7 @@
 from matter_idl.generators.idl import IdlGenerator
 from matter_idl.generators.java import JavaClassGenerator, JavaJNIGenerator
 from matter_idl.generators.kotlin import KotlinClassGenerator
+from matter_idl.generators.markdown import SummaryMarkdownGenerator
 
 
 class CodeGenerator(enum.Enum):
@@ -34,6 +35,7 @@ class CodeGenerator(enum.Enum):
     CPP_APPLICATION = enum.auto()
     CPP_TLVMETA = enum.auto()
     IDL = enum.auto()
+    SUMMARY_MARKDOWN = enum.auto()
     CUSTOM = enum.auto()
 
     def Create(self, *args, **kargs):
@@ -49,6 +51,8 @@ def Create(self, *args, **kargs):
             return TLVMetaDataGenerator(*args, **kargs)
         elif self == CodeGenerator.IDL:
             return IdlGenerator(*args, **kargs)
+        elif self == CodeGenerator.SUMMARY_MARKDOWN:
+            return SummaryMarkdownGenerator(*args, **kargs)
         elif self == CodeGenerator.CUSTOM:
             # Use a package naming convention to find the custom generator:
             # ./matter_idl_plugin/__init__.py defines a subclass of CodeGenerator named CustomGenerator.
@@ -80,5 +84,6 @@ def FromString(name):
     'cpp-app': CodeGenerator.CPP_APPLICATION,
     'cpp-tlvmeta': CodeGenerator.CPP_TLVMETA,
     'idl': CodeGenerator.IDL,
+    'summary-markdown': CodeGenerator.SUMMARY_MARKDOWN,
     'custom': CodeGenerator.CUSTOM,
 }
diff --git a/scripts/tools/zap_regen_all.py b/scripts/tools/zap_regen_all.py
@@ -438,6 +438,11 @@ def getCodegenTemplates():
         idl_path="src/controller/data_model/controller-clusters.matter",
         output_directory="src/controller/java/generated"))
 
+    targets.append(JinjaCodegenTarget(
+        generator="summary-markdown",
+        idl_path="src/controller/data_model/controller-clusters.matter",
+        output_directory="docs"))
+
     return targets