DOC: Json schema exporter.

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

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 -------------------------------------------------
 

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>

src/doc/json_schema_exporter.rst

+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.