Documentation for json schema exporter

Summary

Adding jsex docs to the main documentation and enhancing the docstring.

Focus

Is this accurate? Sufficient?

Test Environment

make doc && xdg-open build/html/index.html

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related issues caosdb/customers/dimr/management#232
• Up-to-date CHANGELOG.md (or not necessary)
• Up-to-date JSON schema (or not necessary)
• Appropriate user and developer documentation (or not necessary)
  • How do I use the software? Assume "stupid" users.
  • How do I develop or debug the software? Assume novice developers.
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md (or not necessary)
• Appropriate user and developer documentation (or not necessary)
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there specifications? Are they satisfied?

For further good practices have a look at our review guidelines.

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