Restructure documentation to have more clearly identifiable types of …

…information -Guides vs. Explanation cs. Reference- in line with the Diataxis documentation framework; and add our first real guide describing how to add your own layer
Netherlands3D · Oct 26, 2024 · 89b9a03 · 89b9a03
1 parent ece845f
commit 89b9a03
Show file tree

Hide file tree

Showing 79 changed files with 116 additions and 29 deletions.
diff --git a/docs/docs/developers/adding-a-simple-type-of-layer.md b/docs/docs/developers/adding-a-simple-type-of-layer.md
@@ -0,0 +1,83 @@
+In this step-by-step guide, you’ll learn to add a new layer type, ideal for developers ready to start
+building within the platform.
+
+_Note: Steps 6 and 7 may change as functionalities become more independent, reducing the need for adjustments in the 
+Twin application._
+
+**Step 1: Pick a Functionality, or Create a New One**
+
+![Adding a functionality with prefabs](../imgs/adding-a-simple-type-of-layer/adding-a-functionality-with-prefabs.png){ align=right width="275" }
+Layers are part of a Functionality and to maintain the necessary structure it is recommended to pick the functionality
+to which the layer should belong or, if this is the first time adding your own material,it is recommended to create 
+your own.
+
+To create a Functionality, create a subfolder in `Assets/_Functionalities` and name it after the functionality that will 
+manage this new layer, and add a new subfolder `Prefabs` to it; here we will place our new layer prefab.
+
+---
+
+**Step 2: Create a Prefab to Visualize the Layer**
+
+Create a new prefab to represent your layer. This can include 3D objects as needed for the layer's visual appearance.
+This prefab serves as the visual representation of your data in the 3D viewer.
+
+_An example of this could be a Prefab that we call '2 Cubes', where we add two Cubes from Unity's '3D Object' creation 
+menu._
+
+---
+
+**Step 3: Attach the `HierarchicalObjectLayerGameObject` Component**
+
+![Attach a HierarchicalObjectLayerGameObject component](../imgs/adding-a-simple-type-of-layer/attach-hierarchical-object-layer-game-object.png){ align=right width="275" }
+
+Add the `HierarchicalObjectLayerGameObject` MonoBehaviour to your prefab. Leave the `Prefab Identifier` field empty or
+assign a unique identifier to make sure this layer is globally unique. This identifier will allow the prefab to register
+as a new layer within the layer system upon instantiation.
+
+_This component will automatically add a Layer -to the project and in the UI- when an instance of this prefab is 
+added to the scene._ 
+
+!!! info "Leaving the `Prefab Identifier` empty will allow for the `PrefabLibrary` (see Step 6) to assign a unique identifier, thus populating it when the prefab is added to the library."
+
+---
+
+**Step 4: Add the WorldTransform Component**
+
+![Attach a world transform](../imgs/adding-a-simple-type-of-layer/attach-a-world-transform.png){ align=right width="275" }
+
+To ensure the object holds real-world coordinates and remains anchored in place as the user navigates, add the
+WorldTransform MonoBehaviour to your prefab. This enables the object to maintain accurate positioning in the 3D
+environment.
+
+_The World Transform is similar to, and extends, Unity's own Transform, it provides the means for an object to be 
+located in a real world position and to track that._ 
+
+!!! warning "When you want to move a GameObject with a WorldTransform, it is highly recommended to do that by changing the Coordinates on the WorldTransform instead of the `transform.position`."
+
+---
+
+**Step 5: (Optional) Add Transform properties to your layer**
+
+![Add a transform property section](../imgs/adding-a-simple-type-of-layer/add-transform-property-section.png){ align=right width="275" }
+
+If you want users to reposition, rotate, or scale this layer in the viewer, add the
+`HierarchicalObjectPropertySectionInstantiator` component. Set its _Property Section Reference_ to 
+`TransformPropertySection`, enabling these manipulations within the project and allowing them to persist in the 
+`.nl3d` project file.
+
+_You can learn more about properties and property sections in the explanation section of the documentation._
+
+---
+
+**Step 6: Register the Prefab in the PrefabLibrary**
+
+To ensure the layer system recognizes and loads this layer, add your prefab to the `PrefabLibrary` ScriptableObject. In 
+it, you can either create a new prefab group or add it to an existing one for organization.
+
+---
+
+**Step 7: (If Needed) Create UI Elements to Add Your Layer**
+
+If you created a new prefab group, or added your prefab to a group without the `auto-populate UI` toggle enabled, add 
+UI elements to allow users to instantiate this layer. The default location is within the `AddLayerPanel` prefab, which 
+serves as the UI hub for adding layers.
diff --git a/docs/docs/imgs/DataKoppelen/image1.png b/docs/docs/imgs/DataKoppelen/image1.png
diff --git a/docs/docs/imgs/DataKoppelen/image2.png b/docs/docs/imgs/DataKoppelen/image2.png
diff --git a/docs/docs/imgs/DataKoppelen/image3.png b/docs/docs/imgs/DataKoppelen/image3.png
diff --git a/docs/docs/imgs/DataKoppelen/image4.png b/docs/docs/imgs/DataKoppelen/image4.png
diff --git a/docs/docs/imgs/adding-a-simple-type-of-layer/add-transform-property-section.png b/docs/docs/imgs/adding-a-simple-type-of-layer/add-transform-property-section.png
diff --git a/...docs/imgs/adding-a-simple-type-of-layer/adding-a-functionality-with-prefabs.png b/...docs/imgs/adding-a-simple-type-of-layer/adding-a-functionality-with-prefabs.png
diff --git a/docs/docs/imgs/adding-a-simple-type-of-layer/attach-a-world-transform.png b/docs/docs/imgs/adding-a-simple-type-of-layer/attach-a-world-transform.png
diff --git a/.../adding-a-simple-type-of-layer/attach-hierarchical-object-layer-game-object.png b/.../adding-a-simple-type-of-layer/attach-hierarchical-object-layer-game-object.png
diff --git a/docs/docs/imgs/bag/image1.png b/docs/docs/imgs/bag/image1.png
diff --git a/docs/docs/imgs/bag/image2.png b/docs/docs/imgs/bag/image2.png
diff --git a/docs/docs/imgs/bag/image3.png b/docs/docs/imgs/bag/image3.png
diff --git a/docs/docs/imgs/bag/image4.png b/docs/docs/imgs/bag/image4.png
diff --git a/docs/docs/imgs/basis/image1.png b/docs/docs/imgs/basis/image1.png
diff --git a/docs/docs/imgs/basis/image10.png b/docs/docs/imgs/basis/image10.png
diff --git a/docs/docs/imgs/basis/image11.png b/docs/docs/imgs/basis/image11.png
diff --git a/docs/docs/imgs/basis/image12.png b/docs/docs/imgs/basis/image12.png
diff --git a/docs/docs/imgs/basis/image13.png b/docs/docs/imgs/basis/image13.png
diff --git a/docs/docs/imgs/basis/image14.png b/docs/docs/imgs/basis/image14.png
diff --git a/docs/docs/imgs/basis/image15.png b/docs/docs/imgs/basis/image15.png
diff --git a/docs/docs/imgs/basis/image16.png b/docs/docs/imgs/basis/image16.png
diff --git a/docs/docs/imgs/basis/image17.png b/docs/docs/imgs/basis/image17.png
diff --git a/docs/docs/imgs/basis/image18.png b/docs/docs/imgs/basis/image18.png
diff --git a/docs/docs/imgs/basis/image19.png b/docs/docs/imgs/basis/image19.png
diff --git a/docs/docs/imgs/basis/image2.png b/docs/docs/imgs/basis/image2.png
diff --git a/docs/docs/imgs/basis/image20.png b/docs/docs/imgs/basis/image20.png
diff --git a/docs/docs/imgs/basis/image21.png b/docs/docs/imgs/basis/image21.png
diff --git a/docs/docs/imgs/basis/image3.png b/docs/docs/imgs/basis/image3.png
diff --git a/docs/docs/imgs/basis/image4.png b/docs/docs/imgs/basis/image4.png
diff --git a/docs/docs/imgs/basis/image5.png b/docs/docs/imgs/basis/image5.png
diff --git a/docs/docs/imgs/basis/image6.png b/docs/docs/imgs/basis/image6.png
diff --git a/docs/docs/imgs/basis/image7.png b/docs/docs/imgs/basis/image7.png
diff --git a/docs/docs/imgs/basis/image8.png b/docs/docs/imgs/basis/image8.png
diff --git a/docs/docs/imgs/basis/image9.png b/docs/docs/imgs/basis/image9.png
diff --git a/docs/docs/imgs/beginnen/create_folder.png b/docs/docs/imgs/beginnen/create_folder.png
diff --git a/docs/docs/imgs/beginnen/editor_herstart.png b/docs/docs/imgs/beginnen/editor_herstart.png
diff --git a/docs/docs/imgs/beginnen/image0.png b/docs/docs/imgs/beginnen/image0.png
diff --git a/docs/docs/imgs/beginnen/image1.png b/docs/docs/imgs/beginnen/image1.png
diff --git a/docs/docs/imgs/beginnen/image10.png b/docs/docs/imgs/beginnen/image10.png
diff --git a/docs/docs/imgs/beginnen/image11.png b/docs/docs/imgs/beginnen/image11.png
diff --git a/docs/docs/imgs/beginnen/image12.png b/docs/docs/imgs/beginnen/image12.png
diff --git a/docs/docs/imgs/beginnen/image13.png b/docs/docs/imgs/beginnen/image13.png
diff --git a/docs/docs/imgs/beginnen/image14.png b/docs/docs/imgs/beginnen/image14.png
diff --git a/docs/docs/imgs/beginnen/image15.png b/docs/docs/imgs/beginnen/image15.png
diff --git a/docs/docs/imgs/beginnen/image16.png b/docs/docs/imgs/beginnen/image16.png
diff --git a/docs/docs/imgs/beginnen/image17.png b/docs/docs/imgs/beginnen/image17.png
diff --git a/docs/docs/imgs/beginnen/image2.png b/docs/docs/imgs/beginnen/image2.png
diff --git a/docs/docs/imgs/beginnen/image3.png b/docs/docs/imgs/beginnen/image3.png
diff --git a/docs/docs/imgs/beginnen/image4.png b/docs/docs/imgs/beginnen/image4.png
diff --git a/docs/docs/imgs/beginnen/image5.png b/docs/docs/imgs/beginnen/image5.png
diff --git a/docs/docs/imgs/beginnen/image6.png b/docs/docs/imgs/beginnen/image6.png
diff --git a/docs/docs/imgs/beginnen/image7.png b/docs/docs/imgs/beginnen/image7.png
diff --git a/docs/docs/imgs/beginnen/image8.png b/docs/docs/imgs/beginnen/image8.png
diff --git a/docs/docs/imgs/beginnen/image9.png b/docs/docs/imgs/beginnen/image9.png
diff --git a/docs/docs/imgs/beginnen/new_project.png b/docs/docs/imgs/beginnen/new_project.png
diff --git a/docs/docs/imgs/camera/image1.png b/docs/docs/imgs/camera/image1.png
diff --git a/docs/docs/imgs/camera/image2.png b/docs/docs/imgs/camera/image2.png
diff --git a/docs/docs/imgs/camera/image3.png b/docs/docs/imgs/camera/image3.png
diff --git a/docs/docs/imgs/dataklaarzetten/image1.png b/docs/docs/imgs/dataklaarzetten/image1.png
diff --git a/docs/docs/imgs/dataklaarzetten/image10.png b/docs/docs/imgs/dataklaarzetten/image10.png
diff --git a/docs/docs/imgs/dataklaarzetten/image2.png b/docs/docs/imgs/dataklaarzetten/image2.png
diff --git a/docs/docs/imgs/dataklaarzetten/image3.png b/docs/docs/imgs/dataklaarzetten/image3.png
diff --git a/docs/docs/imgs/dataklaarzetten/image4.png b/docs/docs/imgs/dataklaarzetten/image4.png
diff --git a/docs/docs/imgs/dataklaarzetten/image5.png b/docs/docs/imgs/dataklaarzetten/image5.png
diff --git a/docs/docs/imgs/dataklaarzetten/image6.png b/docs/docs/imgs/dataklaarzetten/image6.png
diff --git a/docs/docs/imgs/dataklaarzetten/image7.png b/docs/docs/imgs/dataklaarzetten/image7.png
diff --git a/docs/docs/imgs/dataklaarzetten/image8.png b/docs/docs/imgs/dataklaarzetten/image8.png
diff --git a/docs/docs/imgs/dataklaarzetten/image9.png b/docs/docs/imgs/dataklaarzetten/image9.png
diff --git a/docs/docs/imgs/wms/image01.png b/docs/docs/imgs/wms/image01.png
diff --git a/docs/docs/imgs/wms/image02.png b/docs/docs/imgs/wms/image02.png
diff --git a/docs/docs/imgs/wms/image03.png b/docs/docs/imgs/wms/image03.png
diff --git a/docs/docs/imgs/wms/image04.png b/docs/docs/imgs/wms/image04.png
diff --git a/docs/docs/imgs/wms/image05.png b/docs/docs/imgs/wms/image05.png
diff --git a/docs/docs/imgs/wms/image06.png b/docs/docs/imgs/wms/image06.png
diff --git a/docs/docs/imgs/zonnestand/image1.png b/docs/docs/imgs/zonnestand/image1.png
diff --git a/docs/docs/imgs/zonnestand/image2.png b/docs/docs/imgs/zonnestand/image2.png
diff --git a/docs/docs/imgs/zonnestand/image3.png b/docs/docs/imgs/zonnestand/image3.png
diff --git a/docs/docs/imgs/zonnestand/image4.png b/docs/docs/imgs/zonnestand/image4.png
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,41 +8,46 @@ nav:
 #      - 'docs/organisations/personalisering.md'
   - 'Voor ontwikkelaars':
       - 'docs/developers/introduction.md'
-      - 'docs/developers/quickstart.md'
       - 'Platform Architecture':
         - 'Platform Overview': 'docs/developers/platform-architecture.md'
         - 'docs/developers/functionalities.md'
 #      - 'Getting Started':
 #        - 'docs/developers/getting-started/using-the-twin.md'
 #        - 'docs/developers/getting-started/from-scratch.md'
 #        - 'docs/developers/getting-started/your-own-functionality.md'
-      - 'Core Concepts':
-          - 'Overview': 'docs/developers/core-concepts.md'
-          - 'docs/developers/projects.md'
-          - 'docs/developers/layers.md'
-          - 'docs/developers/layers-with-authentication.md'
-      - 'Features':
-          - 'docs/developers/features/embedding.md'
-          - 'docs/developers/features/floating-origin.md'
-          - 'docs/developers/features/geojson.md'
-      - 'Packages':
-          - 'docs/developers/packages/creating-and-managing.md'
-      - 'User interface':
-          - 'docs/developers/ui/introduction.md'
-          - 'docs/developers/ui/keeping-our-documentation-current.md'
-          - 'docs/developers/ui/understanding-blocks.md'
-          - 'docs/developers/ui/understanding-components.md'
-          - 'Blocks':
-              - 'docs/developers/ui/blocks/property-panel-and-sections.md'
-          - 'Components':
-              - 'docs/developers/ui/components/accordion.md'
-              - 'docs/developers/ui/components/cards.md'
-              - 'docs/developers/ui/components/sliders.md'
-              - 'docs/developers/ui/components/double-sliders.md'
-              - 'docs/developers/ui/components/text-fields.md'
-      - 'Architectural Decisions':
-          - 'docs/developers/decisions/index.md'
-          - 'docs/developers/decisions/20241009-styling-of-layers.md'
+      - 'Guides':
+          - 'docs/developers/quickstart.md'
+          - 'docs/developers/adding-a-simple-type-of-layer.md'
+      - 'Explanation':
+        - 'Core Concepts':
+            - 'Overview': 'docs/developers/core-concepts.md'
+            - 'docs/developers/projects.md'
+            - 'docs/developers/layers.md'
+            - 'docs/developers/layers-with-authentication.md'
+        - 'Features':
+            - 'docs/developers/features/embedding.md'
+            - 'docs/developers/features/floating-origin.md'
+            - 'docs/developers/features/geojson.md'
+        - 'Packages':
+            - 'docs/developers/packages/creating-and-managing.md'
+        - 'User interface':
+            - 'docs/developers/ui/introduction.md'
+            - 'docs/developers/ui/keeping-our-documentation-current.md'
+            - 'docs/developers/ui/understanding-blocks.md'
+            - 'docs/developers/ui/understanding-components.md'
+      - 'Reference':
+        - 'Architectural Decisions':
+            - 'docs/developers/decisions/index.md'
+            - 'docs/developers/decisions/20241009-styling-of-layers.md'
+        - 'User interface':
+            - 'Blocks':
+                - 'docs/developers/ui/blocks/property-panel-and-sections.md'
+            - 'Components':
+                - 'docs/developers/ui/components/accordion.md'
+                - 'docs/developers/ui/components/cards.md'
+                - 'docs/developers/ui/components/sliders.md'
+                - 'docs/developers/ui/components/double-sliders.md'
+                - 'docs/developers/ui/components/text-fields.md'
       - 'Contributing':
           - 'docs/developers/contributing/coding-standards.md'
           - 'docs/developers/contributing/documentation.md'
@@ -90,7 +95,6 @@ theme:
     - navigation.sections
     - navigation.tabs
     - navigation.instant
-    - navigation.expand
     - navigation.path
     - navigation.footer
     - navigation.tracking