From 0eec1658f717ec7f1683b7d2a004c8f3396ecdc8 Mon Sep 17 00:00:00 2001
From: tomvanmele <tom.v.mele@gmail.com>
Date: Wed, 2 Oct 2024 20:39:04 +0200
Subject: [PATCH] first draft of guide for creating new data type

---
 docs/devguide/dtypes.rst | 75 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/docs/devguide/dtypes.rst b/docs/devguide/dtypes.rst
index 5a12dffe0ae2..598052a32bf4 100644
--- a/docs/devguide/dtypes.rst
+++ b/docs/devguide/dtypes.rst
@@ -1,2 +1,77 @@
 Implementing a New Data Type
 ============================
+
+COMPAS data types are classes that are based on :class:`compas.data.Data`.
+
+Data types can be serialised to JSON with
+
+* :func:`compas.json_dump`
+* :func:`compas.json_dumps`
+* :func:`compas.json_dumpz`
+
+and deserialised with the corresponding "load" functions
+
+* :func:`compas.json_load`
+* :func:`compas.json_loads`
+* :func:`compas.json_loadz`
+
+All geometry objects and data structures,
+and also, for example, the visualisation scene,
+are data types.
+
+
+Creating a new data type
+========================
+
+A new data type can be created in a few simple steps.
+
+.. code-block:: python
+
+    class CustomData(Data):
+
+        def __init__(self, a=None, b=None, name=None)
+            super().__init__(name=name)
+            self.a = a
+            self.b = b
+
+        @property
+        def __data__(self):
+            data = super().__data__
+            data['a'] = self.a
+            data['b'] = self.b
+            return data
+
+
+>>> data = CustomData(a=1, b=2)
+>>> compas.json_dump(data, "custom.json")
+>>> result = compas.json_load("custom.json")
+>>> isinstance(result, CustomData)
+True
+>>> result.a
+1
+>>> result.b
+2
+
+
+Attribute types
+===============
+
+More info coming soon...
+
+.. note::
+
+    Note that this process can be further simplified
+    by leveraging the ``__annotations__`` infrastructure of Python 3.
+    This will be introduced in the next major COMPAS release.
+
+
+Extending an existing data type
+===============================
+
+More info coming soon...
+
+
+Special Cases
+=============
+
+More info coming soon...