Formatting

doc/development/api/datasync.rst

@@ -15,6 +15,7 @@ An :class:`OutboundSyncProvider` for registering event participants in a mailing
 like this, for example:
 
 .. code-block:: python
+
     from pretix.base.datasync.datasync import OutboundSyncProvider
 
     class MyListSyncProvider(OutboundSyncProvider):
@@ -40,7 +41,7 @@ transferred into which data structures in the external system.
 
 Otherwise, you can use a ``PropertyMappingFormSet`` to let the user set up a mapping from pretix model fields
 to external data fields. You could store the mapping information either in the event settings, or in a separate
-data model. Your implementation of :method:``OutboundSyncProvider.mappings``
+data model. Your implementation of :func:`OutboundSyncProvider.mappings`
 needs to provide a list of mappings, with at least the properties defined in
 :class:`pretix.base.datasync.datasync.StaticMapping`.
 
@@ -83,45 +84,46 @@ shown. Therein, a ``sync_object_with_properties`` method is defined like as foll
             self, identifier_field, identifier_value, properties: list, inputs: dict,
             mapping, mapped_objects: dict, **kwargs,
     ):
-        pre_existing_object = self.fake_api_client.retrieve_object(mapping.external_object_type, identifier_field, identifier_value)
+        # First, we query the external service if our object-to-sync already exists there.
+        # This is necessary to make sure our method is idempotent, i.e. handles already synced
+        # data gracefully.
+        pre_existing_object = self.fake_api_client.retrieve_object(
+            mapping.external_object_type,
+            identifier_field,
+            identifier_value
+        )
 
-First, we query the external service if our object-to-sync already exists there.
-This is necessary to make sure our method is idempotent, i.e. handles already synced data
-gracefully.
-
-.. code-block:: python
-
-        update_values = assign_properties(properties, pre_existing_object or {}, is_new=pre_existing_object is None)
-
-We use the helper function assign_properties to update a pre-existing object.
-
-.. code-block:: python
+        # We use the helper function ``assign_properties`` to update a pre-existing object.
+        update_values = assign_properties(
+            new_values=properties,
+            old_vlaues=pre_existing_object or {},
+            is_new=pre_existing_object is None
+        )
 
+        # Then we can send our new data to the external service. The specifics of course depends
+        # on your API, e.g. you may need to use different endpoints for creating or updating an
+        # object, or pass the identifier separately instead of in the same dictionary as the
+        # other properties.
         result = self.fake_api_client.create_or_update_object(mapping.external_object_type, {
             **update_values,
             identifier_field: identifier_value,
             "_id": pre_existing_object and pre_existing_object.get("_id"),
         })
 
-Then we can send our new data to the external service. The specifics of course depends on your API, e.g. you may
-need to use different endpoints for creating or updating an object, or pass the identifier separately instead of
-in the same dictionary as the other properties.
-
-.. code-block:: python
-
+        # Finally, return a dictionary containing at least `object_type`, `identifier_field`,
+        # `identifier_value`, `external_link_href`, and `external_link_display_name` keys.
+        # Further keys may be provided for your internal use. This dictionary is provided
+        # in following calls in the ``mapped_objects`` dict, to allow creating associations
+        # to this object.
         return {
             "object_type": mapping.external_object_type,
             "identifier_field": identifier_field,
             "identifier_value": identifier_value,
-            "external_link_href": f"https://external-system.example.com/backend/link/to/{mapping.external_object_type}/{identifier_value}/",
+            "external_link_href": f"https://example.org/external-system/{mapping.external_object_type}/{identifier_value}/",
             "external_link_display_name": f"Contact #{identifier_value} - Jane Doe",
             "my_result": result,
         }
 
-Finally, return a dictionary containing at least `object_type`, `identifier_field`, `identifier_value`,
-`external_link_href`, and `external_link_display_name` keys. Further keys may be provided for your internal use.
-This dictionary is provided in following calls in the ``mapped_objects`` dict, to allow creating associations to
-this object.
 
 In :class:`OrderAndTicketAssociationSync`, an example is given where orders, order positions,
 and the association between them are transferred.