Merge pull request #56 from JWCook/fancy-docs

Closes #52. This follows up from [PR #54](#54) and adds sample response data, usage examples, and unit tests for the few endpoints that didn't previously have any:

- [x] `node_api.get_observations()`
- [x] `node_api.get_all_observations()`
- [x] `rest_api.get_all_observation_fields()`
- [x] `rest_api.add_photo_to_observation()`

docs/Makefile

@@ -19,3 +19,4 @@ clean-apidoc:
 # Catch-all target: route all unknown targets to Sphinx builder
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	# E.g: sphinx-build -M html . _build

pyinaturalist/node_api.py

@@ -97,13 +97,31 @@ def get_observation(observation_id: int, user_agent: str = None) -> JsonResponse
     raise ObservationNotFound()
 
 
-# TODO: Example + sample response
 @document_request_params(get_observations_params)
 def get_observations(params: Dict = None, user_agent: str = None, **kwargs) -> JsonResponse:
     """Search observations.
 
     **API reference:** http://api.inaturalist.org/v1/docs/#!/Observations/get_observations
 
+    Example:
+
+        >>> # Get observations of Monarch butterflies with photos + public location info,
+        >>> # on a specific date in the provice of Saskatchewan, CA
+        >>> observations = get_observations(
+        >>>     taxon_name='Danaus plexippus',
+        >>>     created_on='2020-08-27',
+        >>>     photos=True,
+        >>>     geo=True,
+        >>>     geoprivacy='open',
+        >>>     place_id=7953,
+        >>> )
+
+        .. admonition:: Example Response
+            :class: toggle
+
+            .. literalinclude:: ../sample_data/get_observations_node_page_1.json
+                :language: JSON
+
     Returns:
         JSON response containing observation records
     """
@@ -113,7 +131,6 @@ def get_observations(params: Dict = None, user_agent: str = None, **kwargs) -> J
     return r.json()
 
 
-# TODO: Example + sample response
 @document_request_params(get_all_observations_params)
 def get_all_observations(
     params: Dict = None, user_agent: str = None, **kwargs
@@ -126,8 +143,16 @@ def get_all_observations(
     retrieving records from large result sets. If you need to retrieve large numbers of records,
     use the ``per_page`` and ``id_above`` or ``id_below`` parameters instead."
 
+    Example:
+
+        >>> observations = get_all_observations(
+        >>>     taxon_name='Danaus plexippus',
+        >>>     created_on='2020-08-27',
+        >>> )
+
     Returns:
-        Combined list of observation records
+        Combined list of observation records. Response format is the same as the inner "results"
+        object returned by :py:func:`.get_observations()`.
     """
     kwargs = check_deprecated_params(params, **kwargs)
     results = []  # type: List[JsonResponse]

pyinaturalist/request_params.py

@@ -120,7 +120,7 @@
     "geoprivacy": GEOPRIVACY_LEVELS,
     "has": HAS_PROPERTIES,
     "hrank": RANKS,
-    "iconic_taxa": ICONIC_TAXA.values(),
+    "iconic_taxa": list(ICONIC_TAXA.values()),
     "identifications": COMMUNITY_ID_STATUSES,
     "license": CC_LICENSES,
     "lrank": RANKS,

pyinaturalist/rest_api.py

@@ -170,8 +170,13 @@ def get_all_observation_fields(**kwargs) -> List[Dict[str, Any]]:
     """
     Like :py:func:`.get_observation_fields()`, but handles pagination for you.
 
+    Example:
+
+        >>> get_all_observation_fields(q='number of')
+
     Returns:
-        Observation fields as a list of dicts
+        Observation fields as a list of dicts. Response format is the same as the inner
+        "results" object returned by :py:func:`.get_observation_fields`.
     """
     results = []  # type: List[Dict[str, Any]]
     page = 1
@@ -358,7 +363,6 @@ def update_observation(
     return response.json()
 
 
-# TODO: Example + sample response
 # TODO: Support both local file path(s) and object(s)
 def add_photo_to_observation(
     observation_id: int,
@@ -372,16 +376,24 @@ def add_photo_to_observation(
 
     Example:
 
-
         >>> token = get_access_token('...')
         >>> with open('~/observation_photos/2020_09_01_14003156.jpg', 'rb') as f:
         >>>     add_photo_to_observation(1234, f, access_token=token)
 
+        .. admonition:: Example Response
+            :class: toggle
+
+            .. literalinclude:: ../sample_data/add_photo_to_observation.json
+                :language: javascript
+
     Args:
         observation_id: the ID of the observation
         file_object: a file-like object for the picture
         access_token: the access token, as returned by :func:`get_access_token()`
         user_agent: a user-agent string that will be passed to iNaturalist.
+
+    Returns:
+        Information about the newly created photo
     """
     data = {"observation_photo[observation_id]": observation_id}
     file_data = {"file": file_object}

test/sample_data/add_photo_to_observation.json

@@ -0,0 +1,35 @@
+{
+    "id": 1234,
+    "observation_id": 1234,
+    "photo_id": 1234,
+    "position": null,
+    "created_at": "2020-09-24T21:06:16.964-05:00",
+    "updated_at": "2020-09-24T21:06:16.964-05:00",
+    "old_uuid": null,
+    "uuid": "f4ec883f-e835-4590-ab3e-97900bd454a5",
+    "created_at_utc": "2020-09-25T02:06:16.964Z",
+    "updated_at_utc": "2020-09-25T02:06:16.964Z",
+    "photo": {
+        "id": 1234,
+        "user_id": 1234,
+        "native_photo_id": "1234",
+        "square_url": null,
+        "thumb_url": null,
+        "small_url": null,
+        "medium_url": null,
+        "large_url": null,
+        "created_at": "2020-09-24T21:06:15.212-05:00",
+        "updated_at": "2020-09-24T21:06:15.212-05:00",
+        "native_page_url": null,
+        "native_username": "username",
+        "native_realname": "Firstname Lastname",
+        "license": 2,
+        "subtype": null,
+        "native_original_image_url": null,
+        "uuid": "632dddc1-85ad-4664-8438-de6e0afd7746",
+        "license_name": "Creative Commons Attribution-NonCommercial License",
+        "license_url": "http://creativecommons.org/licenses/by-nc/4.0/",
+        "attribution": "(c) Firstname Lastname, some rights reserved (CC BY-NC)",
+        "type": "LocalPhoto"
+    }
+}