Add link to official API docs for each endpoint

pyinaturalist/node_api.py

@@ -59,6 +59,8 @@ def make_inaturalist_api_get_call(endpoint: str, **kwargs) -> requests.Response:
 def get_observation(observation_id: int, user_agent: str = None) -> JsonResponse:
     """Get details about an observation.
 
+    **API reference:** https://api.inaturalist.org/v1/docs/#!/Observations/get_observations_id
+
     Args:
         observation_id: Observation ID
         user_agent: a user-agent string that will be passed to iNaturalist.
@@ -80,7 +82,8 @@ def get_observation(observation_id: int, user_agent: str = None) -> JsonResponse
 @document_request_params(get_observations_params)
 def get_observations(params: Dict = None, user_agent: str = None, **kwargs) -> JsonResponse:
     """Search observations.
-    See: http://api.inaturalist.org/v1/docs/#!/Observations/get_observations
+
+    **API reference:** http://api.inaturalist.org/v1/docs/#!/Observations/get_observations
 
     Returns:
         JSON response containing observation records
@@ -140,7 +143,7 @@ def get_observation_species_counts(user_agent: str = None, **kwargs) -> JsonResp
     criteria, and the count of observations they are associated with.
     **Leaf taxa** are the leaves of the taxonomic tree, e.g., species, subspecies, variety, etc.
 
-    See: https://api.inaturalist.org/v1/docs/#!/Observations/get_observations_species_counts
+    **API reference:** https://api.inaturalist.org/v1/docs/#!/Observations/get_observations_species_counts
 
     Example:
         >>> get_observation_species_counts(user_login='my_username', quality_grade='research')
@@ -196,7 +199,8 @@ def get_geojson_observations(properties: List[str] = None, **kwargs) -> JsonResp
 def get_places_by_id(place_id: MultiInt, user_agent: str = None) -> JsonResponse:
     """
     Get one or more places by ID.
-    See: https://api.inaturalist.org/v1/docs/#!/Places/get_places_id
+
+    **API reference:** https://api.inaturalist.org/v1/docs/#!/Places/get_places_id
 
     Example:
         >>> get_places_by_id(93735)
@@ -229,7 +233,8 @@ def get_places_nearby(user_agent: str = None, **kwargs) -> JsonResponse:
     """
     Given an bounding box, and an optional name query, return standard iNaturalist curator approved
     and community non-curated places nearby
-    See: https://api.inaturalist.org/v1/docs/#!/Places/get_places_nearby
+
+    **API reference:** https://api.inaturalist.org/v1/docs/#!/Places/get_places_nearby
 
     Example:
         >>> bounding_box = (150.0, -50.0, -149.999, -49.999)
@@ -263,7 +268,8 @@ def _convert_all_locations_to_float(response):
 
 def get_places_autocomplete(q: str, user_agent: str = None) -> JsonResponse:
     """Given a query string, get places with names starting with the search term
-    See: https://api.inaturalist.org/v1/docs/#!/Places/get_places_autocomplete
+
+    **API reference:** https://api.inaturalist.org/v1/docs/#!/Places/get_places_autocomplete
 
     Example:
         >>> get_places_autocomplete('Irkutsk')
@@ -291,7 +297,8 @@ def get_places_autocomplete(q: str, user_agent: str = None) -> JsonResponse:
 
 def get_taxa_by_id(taxon_id: MultiInt, user_agent: str = None) -> JsonResponse:
     """Get one or more taxa by ID.
-    See: https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa_id
+
+    **API reference:** https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa_id
 
     Args:
         taxon_id: Get taxa with this ID. Multiple values are allowed.
@@ -309,7 +316,8 @@ def get_taxa_by_id(taxon_id: MultiInt, user_agent: str = None) -> JsonResponse:
 @document_request_params(get_taxa_params)
 def get_taxa(user_agent: str = None, **kwargs) -> JsonResponse:
     """Given zero to many of following parameters, returns taxa matching the search criteria.
-    See https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa
+
+    **API reference:** https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa
 
     Returns:
         A list of dicts containing taxa results
@@ -323,7 +331,8 @@ def get_taxa(user_agent: str = None, **kwargs) -> JsonResponse:
 @document_request_params(get_taxa_autocomplete_params)
 def get_taxa_autocomplete(user_agent: str = None, **kwargs) -> JsonResponse:
     """Given a query string, returns taxa with names starting with the search term
-    See: https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa_autocomplete
+
+    **API reference:** https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa_autocomplete
 
     **Note:** There appears to currently be a bug in the API that causes ``per_page`` to not have
     any effect.

pyinaturalist/rest_api.py

@@ -30,7 +30,7 @@ def get_observations(user_agent: str = None, **params) -> Union[List, str]:
     :py:func:`.get_geojson_observations` for GeoJSON format (not included here because it wraps
     a separate API endpoint).
 
-    For API parameters, see: https://www.inaturalist.org/pages/api+reference#get-observations
+    **API reference:** https://www.inaturalist.org/pages/api+reference#get-observations
 
     Example::
 
@@ -62,7 +62,8 @@ def get_observations(user_agent: str = None, **params) -> Union[List, str]:
 def get_observation_fields(user_agent: str = None, **kwargs) -> List[Dict[str, Any]]:
     """Search observation fields. Observation fields are basically typed data fields that
     users can attach to observation.
-    API reference: https://www.inaturalist.org/pages/api+reference#get-observation_fields
+
+    **API reference:** https://www.inaturalist.org/pages/api+reference#get-observation_fields
 
     Returns:
         Observation fields as a list of dicts
@@ -115,6 +116,8 @@ def put_observation_field_values(
     """Set an observation field (value) on an observation.
     Will fail if this observation_field is already set for this observation.
 
+    **API reference:** https://www.inaturalist.org/pages/api+reference#put-observation_field_values-id
+
     Example:
             >>> put_observation_field_values(
             >>>     observation_id=7345179,
@@ -172,6 +175,8 @@ def get_access_token(
     """Get an access token using the user's iNaturalist username and password.
     You still need an iNaturalist app to do this.
 
+    **API reference:** https://www.inaturalist.org/pages/api+reference#auth
+
     Example:
         >>> access_token = get_access_token('...')
         >>> headers = {"Authorization": f"Bearer {access_token}"}
@@ -202,6 +207,7 @@ def get_access_token(
         raise AuthenticationError("Authentication error, please check credentials.")
 
 
+# TODO: Support either local file path(s) or object(s)
 def add_photo_to_observation(
     observation_id: int,
     file_object: BinaryIO,
@@ -210,6 +216,8 @@ def add_photo_to_observation(
 ):
     """Upload a picture and assign it to an existing observation.
 
+    **API reference:** https://www.inaturalist.org/pages/api+reference#post-observation_photos
+
     Args:
         observation_id: the ID of the observation
         file_object: a file-like object for the picture. Example: open('/Users/nicolasnoe/vespa.jpg', 'rb')
@@ -231,13 +239,14 @@ def add_photo_to_observation(
 
 
 # TODO: Implement `observation_field_values_attributes`, and simplify nested data structures
-# TODO: implement `local_photos` and allow simply passing local file path(s)
+# TODO: implement `local_photos` and support either local file path(s) or object(s)
 @document_request_params(create_observations_params)
 def create_observations(
     params: Dict[str, Dict[str, Any]], access_token: str, user_agent: str = None, **kwargs
 ) -> List[Dict[str, Any]]:
     """Create one or more observations.
-    For API reference, see: https://www.inaturalist.org/pages/api+reference#post-observations
+
+    **API reference:** https://www.inaturalist.org/pages/api+reference#post-observations
 
     Example:
         >>> params = {'observation': {'species_guess': 'Pieris rapae'}}
@@ -275,7 +284,9 @@ def update_observation(
     observation_id: int, params: Dict[str, Any], access_token: str, user_agent: str = None, **kwargs
 ) -> List[Dict[str, Any]]:
     """
-    Update a single observation. See https://www.inaturalist.org/pages/api+reference#put-observations-id
+    Update a single observation.
+
+    **API reference:** https://www.inaturalist.org/pages/api+reference#put-observations-id
 
     Returns:
         iNaturalist's JSON response, as a Python object
@@ -304,6 +315,8 @@ def delete_observation(observation_id: int, access_token: str = None, user_agent
     """
     Delete an observation.
 
+    **API reference:** https://www.inaturalist.org/pages/api+reference#delete-observations-id
+
     Returns:
         If successful, no response is returned from this endpoint