From 4d1a2679754cf385519dcfde93de343931dbe4ca Mon Sep 17 00:00:00 2001
From: Daniel <d.hornung@indiscale.com>
Date: Wed, 10 Apr 2024 12:18:48 +0200
Subject: [PATCH] DOC: Json schema exporter.
---
src/caosadvancedtools/json_schema_exporter.py | 34 +++++++++++++++++--
src/doc/conf.py | 1 +
src/doc/index.rst | 1 +
src/doc/json_schema_exporter.rst | 8 +++++
4 files changed, 42 insertions(+), 2 deletions(-)
create mode 100644 src/doc/json_schema_exporter.rst
diff --git a/src/caosadvancedtools/json_schema_exporter.py b/src/caosadvancedtools/json_schema_exporter.py
index c36c9d0b..c4c6de16 100644
--- a/src/caosadvancedtools/json_schema_exporter.py
+++ b/src/caosadvancedtools/json_schema_exporter.py
@@ -19,9 +19,39 @@
# You should have received a copy of the GNU Affero General Public License along
# with this program. If not, see <https://www.gnu.org/licenses/>.
#
-"""Module for converting a data model into a json schema compatible dictionary.
+"""Convert a data model into a json schema.
+
+Sometimes you may want to have a `json schema <https://json-schema.org>`_ which describes a
+LinkAhead data model, for example for the automatic generation of user interfaces with third-party
+tools like `rjsf <https://rjsf-team.github.io/react-jsonschema-form/docs/>`_. Then this is the
+right module for you!
+
+The :mod:`json_schema_exporter <caosadvancedtools.json_schema_exporter>` module has one main class,
+:class:`JsonSchemaExporter`, and a few utility and wrapper functions.
+
+For easy usage, you may simply import `recordtype_to_json_schema` and use it on a fully referenced
+RecordType like this::
+
+ import caosadvancedtools.models.parser as parser
+ import caosadvancedtools.json_schema_exporter as jsex
+
+ model = parser.parse_model_from_yaml("my_model.yml")
+
+ # get the data model schema for the "Journey" recordtype
+ schema, ui_schema = recordtype_to_json_schema(
+ rt=model.get_deep("Journey"),
+ do_not_create=["Continent"], # only choose from existing Records
+ multiple_choice=["visited_cities"],
+ rjsf=True # also create a UI schema
+ )
+
+For more details on how to use this wrapper, read the `function documentation
+<recordtype_to_json_schema>`.
+
+Other useful functions are `make_array`, which creates an array out of a single schema, and
+`merge_schemas`, which as the name suggests allows to combine multiple schema definitions into a
+single schema.
-The scope of this json schema is the automatic generation of user interfaces.
"""
from collections import OrderedDict
diff --git a/src/doc/conf.py b/src/doc/conf.py
index db77cd71..f4954a59 100644
--- a/src/doc/conf.py
+++ b/src/doc/conf.py
@@ -74,6 +74,7 @@ exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
+default_role = "py:obj"
# -- Options for HTML output -------------------------------------------------
diff --git a/src/doc/index.rst b/src/doc/index.rst
index aa5cedca..7fa017ec 100644
--- a/src/doc/index.rst
+++ b/src/doc/index.rst
@@ -16,6 +16,7 @@ This documentation helps you to :doc:`get started<README_SETUP>`, explains the m
The Caosdb Crawler <crawler>
YAML data model specification <yaml_interface>
Specifying a datamodel with JSON schema <json_schema_interface>
+ Convert a data model into a json schema <json_schema_exporter>
Conversion between XLSX, JSON and LinkAhead Entities <table-json-conversion/specs>
_apidoc/modules
Related Projects <related_projects/index>
diff --git a/src/doc/json_schema_exporter.rst b/src/doc/json_schema_exporter.rst
new file mode 100644
index 00000000..da4fa9d2
--- /dev/null
+++ b/src/doc/json_schema_exporter.rst
@@ -0,0 +1,8 @@
+JSON schema from data model
+===========================
+
+Sometimes you may want to have a `json schema <https://json-schema.org>`_ which describes a
+LinkAhead data model, for example for the automatic generation of user interfaces with third-party
+tools like `rjsf <https://rjsf-team.github.io/react-jsonschema-form/docs/>`_.
+
+For this use case, look at the documentation of the `caosadvancedtools.json_schema_exporter` module.
--
GitLab