Merge pull request #79 from CADET/dt/doc-improvements

Improve docs

docs/explanation/components.md

@@ -9,3 +9,37 @@ may not be appropriate for all classes. The `Location` class in this package is
 cases like that developers can define their own name field and set its default value to `""`.
 
 Refer to the [Components API](#components-api) for more information.
+
+## Inheritance
+Recommended rule: A `Component` that has subclasses should never be directly instantiated.
+
+Consider a scenario where a developer defines a `Load` class and then later decides a new load is
+needed because of one custom field.
+
+The temptation may be to create `CustomLoad(Load)`. This is very problematic in the design of
+the infrasys API. There will be no way to retrieve only `Load` instances. Consider this example:
+
+```python
+for load in system.get_components(Load)
+    print(load.name)
+```
+
+This will retrieve both `Load` and `CustomLoad` instances.
+
+Instead, our recommendation is to create a base class with the common fields.
+
+```python
+class LoadBase(Component)
+    """Defines common fields for all Loads."""
+
+    common_field1: float
+    common_field2: float
+
+class Load(LoadBase):
+    """A load component"""
+
+class CustomLoad(LoadBase):
+    """A custom load component"""
+
+    custom_field: float
+```

docs/reference/index.md

@@ -9,4 +9,5 @@
     :caption: Contents:
 
     api/index
+    system_json
 ```

docs/reference/system_json.md

@@ -0,0 +1,51 @@
+## Viewing System Data in JSON Format
+
+System data can be serialized to JSON files with `system.to_json("system.json")`.
+
+It can be useful to view and filter the system data in this format. There
+are many tools available to browse JSON data.
+
+Here is an example [GUI tool](http://jsonviewer.stack.hu) that is available
+online in a browser.
+
+The command line utility [jq](https://stedolan.github.io/jq/) offers even more
+features. The rest of this page provides example commands.
+
+Some of the examples assume a UNIX operating system (our apologies to Windows users).
+
+- View the entire file pretty-printed
+
+```
+$ jq . system.json
+```
+
+- View the System component types
+
+```
+$ jq -r '.components | .[] | .__metadata__.fields.type' system.json | sort | uniq
+```
+
+- View specific components
+
+```
+$ jq '.components | .[] | select(.__metadata__.fields.type == "Bus")' system.json
+```
+
+- Get the count of a component type
+
+```
+# There is almost certainly a better way.
+$ jq '.components | .[] | select(.__metadata__.fields.type == "Bus")' system.json | grep -c Bus
+```
+
+- View specific component by name
+
+```
+$ jq '.components | .[] | select(.__metadata__.fields.type == "Bus" and .name == "bus1")' system.json
+```
+
+- Filter on a field value
+
+```
+$ jq '.components | .[] | select(.__metadata__.fields.type == "Bus" and .voltage > 1.1)' system.json
+```