DOC Surface civis.find and civis.find_one in the Sphinx docs (civisanalytics#250)

* DOC Use the most up-to-date version number in Sphinx docs

* DOC Minor typos

* DOC Surface find() and find_one() in Sphinx docs

* DOC Remove unnecessary Sphinx ref

* MAINT Update the changelog

Author: jacksonllee

CHANGELOG.md

@@ -25,6 +25,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
   This allows users to select a subset of a model's outputs for scoring (#241).
 - Added `civis.io.export_to_civis_file` to store results of a SQL query
   to a Civis file
+- Surfaced `civis.find` and `civis.find_one` in the Sphinx docs. (#250)
 
 ### Changed
 - Moved "Optional Dependencies" doc section to top of ML docs, and

civis/civis.py

@@ -15,27 +15,28 @@
 
 
 def find(object_list, filter_func=None, **kwargs):
-    """Return the objects from ``object_list`` that satisfy the filters.
+    """Filter :class:`civis.response.Response` objects.
 
     Parameters
     ----------
     object_list : iterable
-        An iterable of arbitrary objects, particularly those with
-        attributes that can be targeted by the filters in ``kwargs``.
-        A major use case is a list of ``civis.response.Response`` objects.
+        An iterable of arbitrary objects, particularly those with attributes
+        that can be targeted by the filters in `kwargs`. A major use case is
+        an iterable of :class:`civis.response.Response` objects.
     filter_func : callable, optional
-        A one-argument function. If specified, ``kwargs`` are ignored.
-        An ``object`` from the input iterable is kept in the returned list
+        A one-argument function. If specified, `kwargs` are ignored.
+        An `object` from the input iterable is kept in the returned list
         if and only if ``bool(filter_func(object))`` is ``True``.
     **kwargs
         Key-value pairs for more fine-grained filtering; they cannot be used
-        in conjunction with ``filter_func``. All keys must be strings.
-        For an ``object`` from the input iterable to be included in the
-        returned list, all the ``key``s must be attributes of ``object``, plus
-        any one of the following conditions for a given ``key``:
-        - ``value`` is a one-argument function and
+        in conjunction with `filter_func`. All keys must be strings.
+        For an `object` from the input iterable to be included in the
+        returned list, all the `key`s must be attributes of `object`, plus
+        any one of the following conditions for a given `key`:
+
+        - `value` is a one-argument function and
           ``bool(value(getattr(object, key)))`` is ``True``
-        - ``value`` is ``True``
+        - `value` is ``True``
         - ``getattr(object, key)`` is equal to ``value``
 
     Returns
@@ -78,9 +79,12 @@ def default_filter(o):
 
 
 def find_one(object_list, filter_func=None, **kwargs):
-    """Return one object (or ``None``) from ``civis.find``.
+    """Return one satisfying :class:`civis.response.Response` object.
 
-    The arguments are the same as those for ``civis.find``.
+    The arguments are the same as those for :func:`civis.find`.
+    If more than one object satisfies the filtering criteria,
+    the first one is returned.
+    If no satisfying objects are found, ``None`` is returned.
 
     Returns
     -------

docs/source/conf.py

@@ -16,6 +16,8 @@
 import os
 import datetime
 
+import civis
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -33,7 +35,7 @@
 
 intersphinx_mapping = {
     'pandas': ('http://pandas.pydata.org/pandas-docs/stable', None),
-    'python': ('https://docs.python.org/3.4', None),
+    'python': ('https://docs.python.org/3', None),
     'requests': ('https://requests.readthedocs.io/en/latest/', None),
     'sklearn': ('http://scikit-learn.org/stable', None),
     'joblib': ('http://pythonhosted.org/joblib', None),
@@ -63,10 +65,11 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+major_version, minor_version, _ = civis.__version__.split('.')
 # The short X.Y version.
-version = '1.0'
+version = '%s.%s' % (major_version, minor_version)
 # The full version, including alpha/beta/rc tags.
-release = '1.0.0'
+release = civis.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/index.rst

@@ -18,7 +18,7 @@ The recommended install method is pip:
 
    pip install civis
 
-Alternatively, you may clone the code from github and build from source:
+Alternatively, you may clone the code from GitHub and build from source:
 
 .. code-block:: bash
 

docs/source/parallel.rst

@@ -18,7 +18,7 @@ tool for your code:
 
 - Each function call which is parallelized with the Civis joblib backend will run
   in a different Civis Platform script. Creating a new script comes with some overhead.
-  It will take between a few seconds an a few minutes for each script to start,
+  It will take between a few seconds and a few minutes for each script to start,
   depending on whether Civis Platform needs to provision additional resources.
   If you expect that each function call will complete quickly, instead consider either
   running them in serial or using extra processes in the same Civis Platform script.

docs/source/responses.rst

@@ -1,5 +1,8 @@
-API Response Types
-==================
+API Responses
+=============
+
+Response Types
+--------------
 
 .. autoclass:: civis.response.Response
    :members:
@@ -9,3 +12,9 @@ API Response Types
 
 .. autoclass:: civis.futures.CivisFuture
    :members:
+
+Helper Functions
+----------------
+
+.. autofunction:: civis.find
+.. autofunction:: civis.find_one

docs/source/user_guide.rst

@@ -185,3 +185,14 @@ example, with pandas.
 .. code:: python
 
    >>> url = export_result.output[0].path
+
+
+API Response Types and Functions
+================================
+
+Many API requests via an :class:`~civis.APIClient` instance return an iterable
+of :class:`civis.response.Response` objects.
+For endpoints that support pagination when the `iterator` kwarg is specified,
+a :class:`civis.response.PaginatedResponse` object is returned.
+To facilitate working with :class:`civis.response.Response` objects,
+the helper functions :func:`civis.find` and :func:`civis.find_one` are defined.