SG-21729 Update docs for entity fields.

docs/cookbook/usage_tips.rst

@@ -31,13 +31,15 @@ Multi-threading
 The ShotGrid API is not thread-safe. If you want to do threading we strongly suggest that you use 
 one connection object per thread and not share the connection.
 
+.. _entity-fields:
+
 *************
 Entity Fields
 *************
 
-When you do a :meth:`~shotgun_api3.Shotgun.find` call that returns a field of type entity or 
-multi-entity (for example the 'assets' column on Shot), the entities are returned in a standard 
-dictionary::
+When you do a :meth:`~shotgun_api3.Shotgun.find` or a :meth:`~shotgun_api3.Shotgun.create` call
+that returns a field of type **entity** or **multi-entity** (for example the 'Assets' column on Shot),
+the entities are returned in a standard dictionary::
 
     {'type': 'Asset', 'name': 'redBall', 'id': 1}
 
@@ -260,6 +262,8 @@ ShotGrid logger to a higher level::
 Optimizations
 *************
 
+.. _combining-related-queries: 
+
 Combining Related Queries
 =========================
 Reducing round-trips for data via the API can significantly improve the speed of your application.
@@ -285,7 +289,7 @@ With "field hopping" you can combine these queries into::
     sg_shots = sg.find("Shot", [['project.Project.name', 'is', project_name]], ['code'])
 
 As you can see above, the syntax is to use "``.``" dot notation, joining field names to entity
-types in a chain. In this example we start with the field ``project`` on the Shot entity, then
+types in a chain. In this example we start with the field ``project`` on the ``Shot`` entity, then
 specify we're looking for the "name" field on the Project entity by specifying ``Project.name``.
 
 Now that we've demonstrated querying using dot notation, let's take a look at returning linked data
@@ -296,7 +300,10 @@ by adding the status of each Sequence entity associated with each Shot in our pr
     sg_shots = sg.find("Shot", [['project.Project.name', 'is', project_name]],
                        ['code', 'sg_sequence.Sequence.sg_status_list'])
 
+The previous examples use the :meth:`~shotgun_api3.Shotgun.find` method. However, it's also applicable
+to the :meth:`~shotgun_api3.Shotgun.create` method.
+
 .. note::
-    Due to performance concerns with deep linking, we only support using dot syntax chains for
+    Due to performance concerns with deep linking, we only support using dot notation chains for
     single-entity relationships. This means that if you try to pull data through a multi-entity
     field you will not get the desired result.

shotgun_api3/shotgun.py

@@ -874,6 +874,9 @@ def find_one(self, entity_type, filters, fields=None, order=None, filter_operato
             :ref:`additional_filter_presets`
         :returns: Dictionary representing a single matching entity with the requested fields,
             and the defaults ``"id"`` and ``"type"`` which are always included.
+
+            .. seealso:: :ref:`entity-fields`
+
         :rtype: dict
         """
 
@@ -910,7 +913,7 @@ def find(self, entity_type, filters, fields=None, order=None, filter_operator=No
              {'code': 'Wet Gopher', 'id': 149, 'sg_asset_type': 'Character', 'type': 'Asset'}]
 
         You can drill through single entity links to filter on fields or display linked fields.
-        This is often called "deep linking" or using "dot syntax".
+        This is often called "deep linking" or using "dot notation".
 
             .. seealso:: :ref:`filter_syntax`
 
@@ -933,10 +936,13 @@ def find(self, entity_type, filters, fields=None, order=None, filter_operator=No
         :param str entity_type: Shotgun entity type to find.
         :param list filters: list of filters to apply to the query.
 
-            .. seealso:: :ref:`filter_syntax`
+            .. seealso:: :ref:`filter_syntax`, :ref:`combining-related-queries`
 
         :param list fields: Optional list of fields to include in each entity record returned.
             Defaults to ``["id"]``.
+
+            .. seealso:: :ref:`combining-related-queries`
+
         :param list order: Optional list of dictionaries defining how to order the results of the
             query. Each dictionary contains the ``field_name`` to order by and  the ``direction``
             to sort::
@@ -970,6 +976,9 @@ def find(self, entity_type, filters, fields=None, order=None, filter_operator=No
             :ref:`additional_filter_presets`
         :returns: list of dictionaries representing each entity with the requested fields, and the
             defaults ``"id"`` and ``"type"`` which are always included.
+
+            .. seealso:: :ref:`entity-fields`
+
         :rtype: list
         """
 
@@ -1332,10 +1341,16 @@ def create(self, entity_type, data, return_fields=None):
             to the server automatically.
         :param list return_fields: Optional list of additional field values to return from the new
             entity. Defaults to ``id`` field.
+
+            .. seealso:: :ref:`combining-related-queries`
+
         :returns: Shotgun entity dictionary containing the field/value pairs of all of the fields
             set from the ``data`` parameter as well as the defaults ``type`` and ``id``. If any
             additional fields were provided using the ``return_fields`` parameter, these would be
             included as well.
+
+            .. seealso:: :ref:`entity-fields`
+
         :rtype: dict
         """