feat: Add auto-generated UML diagram to docs

.pre-commit-config.yaml

@@ -1,40 +1,46 @@
 fail_fast: true
 repos:
-- repo: local
-  hooks:
+  - repo: local
+    hooks:
+      - id: pyink
+        name: pyink
+        entry: poetry run pyink
+        language: system
+        types: [file, python]
+        files: "^smart_control/"
+        exclude: "^smart_control/Dockerfile"
 
-    - id: pyink
-      name: pyink
-      entry: poetry run pyink
-      language: system
-      types: [file, python]
-      files: '^smart_control/'
-      exclude: '^smart_control/Dockerfile'
+      - id: isort
+        name: isort
+        entry: poetry run isort
+        language: system
+        types: [file, python]
+        files: "^smart_control/"
+        exclude: "^smart_control/proto/"
 
-    - id: isort
-      name: isort
-      entry: poetry run isort
-      language: system
-      types: [file, python]
-      files: '^smart_control/'
-      exclude: '^smart_control/proto/'
+      # NOTE: running `pylint` against all files is prohibitively slow
+      # ... so we omit passing the `smart_buildings` directory,
+      # ... which allows pre-commit to run against staged / changed files only
+      - id: pylint
+        name: pylint
+        #entry: pylint --rcfile=.pylintrc --ignore=proto smart_control
+        #entry: pylint --rcfile=.pylintrc --ignore=proto $(git diff --name-only --staged | grep -E '\.py$')
+        entry: pylint --rcfile=.pylintrc --ignore=proto
+        language: system
+        types: [file, python]
+        files: "^smart_control/"
+        exclude: "^smart_control/proto/"
 
-    # NOTE: running `pylint` against all files is prohibitively slow
-    # ... so we omit passing the `smart_buildings` directory,
-    # ... which allows pre-commit to run against staged / changed files only
-    - id: pylint
-      name: pylint
-      #entry: pylint --rcfile=.pylintrc --ignore=proto smart_control
-      #entry: pylint --rcfile=.pylintrc --ignore=proto $(git diff --name-only --staged | grep -E '\.py$')
-      entry: pylint --rcfile=.pylintrc --ignore=proto
-      language: system
-      types: [file, python]
-      files: '^smart_control/'
-      exclude: '^smart_control/proto/'
+      - id: uml-generator
+        name: Generate UML Diagram
+        entry: make uml
+        language: system
+        files: ^smart_control/.*\.py$
+        stages: [commit]
 
-# See: https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#usage-as-a-pre-commit-hook
-- repo: https://github.com/hukkin/mdformat
-  rev: 0.7.22
-  hooks:
-  - id: mdformat
-    exclude: ^docs/api/
+  # See: https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#usage-as-a-pre-commit-hook
+  - repo: https://github.com/hukkin/mdformat
+    rev: 0.7.22
+    hooks:
+      - id: mdformat
+        exclude: ^docs/api/

Makefile

@@ -53,3 +53,12 @@ docs-quiet:
 
 docs-build:
 	poetry run mkdocs build
+
+#
+# UML Diagram
+#
+uml:
+	@echo "--- Generating UML class diagram ---"
+	pyreverse -o dot -p smart_control smart_control/
+	dot -Tpng classes_smart_control.dot -o docs/images/class_diagram.png
+	rm classes_smart_control.dot packages_smart_control.dot

docs/index.md

@@ -8,3 +8,9 @@ efficiency, operational costs, and occupant comfort.
 
 This project is an open source collaboration between Google and partner
 organizations in academia and industry.
+
+## Code Architecture
+
+To help understand the connections between classes, the following UML class diagram is automatically generated from the source code.
+
+![UML Class Diagram](images/class_diagram.png)

docs/setup.md

@@ -11,6 +11,7 @@ This project requires the following system dependencies:
 - [Protocol Buffer Compiler](https://grpc.io/docs/protoc-installation/)
   (`v 3.21.12`)
 - [FFmpeg](https://ffmpeg.org/) (`v 7.1.1`)
+- [Graphviz](https://graphviz.org/download/) (for generating documentation diagrams)
 - Python (`>=3.10.12 and <3.12`)
 
 ## Repository Setup

smart_control/simulator/stochastic_occupancy.py

@@ -54,13 +54,22 @@ def __init__(
       random_state: np.random.RandomState,
       time_zone: Union[datetime.tzinfo, str] = "UTC",
   ):
-    assert (
+    # Validate that the time bounds are in chronological order
+    if not (
         earliest_expected_arrival_hour
         < latest_expected_arrival_hour
         < earliest_expected_departure_hour
         < latest_expected_departure_hour
-    )
-    assert lunch_start_hour < lunch_end_hour
+    ):
+      raise ValueError(
+          "Time bounds must be in chronological order i.e., "
+          "expected arrival/departure hours must be strictly increasing:" "earliest_expected_arrival_hour < latest_expected_arrival_hour "
+          "< earliest_expected_departure_hour < latest_expected_departure_hour."
+      )
+
+    # Validate lunch time bounds
+    if lunch_start_hour >= lunch_end_hour:
+      raise ValueError("lunch_start_hour must be before lunch_end_hour.")
 
     self._earliest_expected_arrival_hour = earliest_expected_arrival_hour
     self._latest_expected_arrival_hour = latest_expected_arrival_hour