DOC: Add screenshots of created records

src/doc/converters.rst

@@ -252,10 +252,10 @@ The :py:class:`~caoscrawler.converters.PropertiesFromDictConverter` is
 a specialization of the
 :py:class:`~caoscrawler.converters.DictElementConverter` and offers
 all its functionality. It is meant to operate on dictionaries (e.g.,
-from reading in a json or a table file) the keys of which correspond
-closely to LinkAhead properties. This is especially handy in cases
-where properties may be added to the data model and data sources after
-the writing of the CFood definition.
+from reading in a json or a table file), the keys of which correspond
+closely to properties in a LinkAhead datamodel. This is especially
+handy in cases where properties may be added to the data model and
+data sources that are not yet known when writing the cfood definition.
 
 The converter definition of the
 :py:class:`~caoscrawler.converters.PropertiesFromDictConverter` has an
@@ -278,7 +278,7 @@ look at a simple example. A CFood definition
 	   - MyType1
 	   - MyType2
 
-applied on a dictionary
+applied to a dictionary
 
 .. code-block:: json
 
@@ -295,11 +295,15 @@ will create a Record ``New name`` with parents ``MyType1`` and
 ``MyType2``. It has a scalar property ``a`` with value 5, a list
 property ``b`` with values "a", "b" and "c", and an ``author``
 property which references an ``author`` with a ``full_name`` property
-with value "Silvia Scientist". Note how the different dictionary keys
-are handled differently depending on their types: scalar and list
-values are understood automatically, and a dictionary-valued entry
-like ``author`` is translated into a reference to an ``author`` Record
-automatically.
+with value "Silvia Scientist":
+
+.. image:: img/properties-from-dict-records-author.png
+  :height: 210
+
+Note how the different dictionary keys are handled differently
+depending on their types: scalar and list values are understood
+automatically, and a dictionary-valued entry like ``author`` is
+translated into a reference to an ``author`` Record automatically.
 
 You can further specify how references are treated with an optional
 ``references key`` in ``record_from_dict``. Let's assume that in the
@@ -325,7 +329,10 @@ extending the above example definition by
 
 so that now, a ``Person`` record with a ``full_name`` property with
 value "Silvia Scientist" is created as the value of the ``author``
-property.
+property:
+
+.. image:: img/properties-from-dict-records-person.png
+  :height: 200
 
 Properties can be blacklisted with the ``properties_blacklist``
 keyword. Since the
@@ -343,13 +350,16 @@ For further customization, the
 used as a basis for :ref:`custom converters<Custom Converters>` which
 can make use of its ``referenced_record_callback`` argument. The
 ``referenced_record_callback`` can be a callable object which takes
-exactly one Record as an argument and needs to return that Record
-after doing whatever custom treatment is needed. It is applied to all
-Records that are created from the dictionary and it can be used to,
-e.g., transform values of some properties, or add special treatment to
-all Records of a specific type. ``referenced_record_callback`` is
-applied **after** the properties from the dictionary have been applied
-as explained above.
+exactly a Record as an argument and needs to return that Record after
+doing whatever custom treatment is needed. Additionally, it is given
+the ``RecordStore`` and the ``ValueStore`` in order to be able to
+access the records and values that have already been defined from
+within ``referenced_record_callback``. It is applied to all Records
+that are created from the dictionary and it can be used to, e.g.,
+transform values of some properties, or add special treatment to all
+Records of a specific type. ``referenced_record_callback`` is applied
+**after** the properties from the dictionary have been applied as
+explained above.
 
 Further converters
 ++++++++++++++++++