Merge pull request #864 from quantopian/docs-improvements

Docs improvements

docs/source/appendix.rst

@@ -1,8 +1,62 @@
-Zipline API
------------
+API Reference
+-------------
 
-For each of these api functions, the ``self`` argument is implicitly the current
-:class:`~zipline.algorithm.TradingAlgorithm`
+Algorithm API
+~~~~~~~~~~~~~
+
+The following methods are available for use in the ``initialize``,
+``handle_data``, and ``before_trading_start`` API functions.
+
+In all listed functions, the ``self`` argument is implicitly the
+currently-executing :class:`~zipline.algorithm.TradingAlgorithm` instance.
 
 .. automodule:: zipline.api
    :members:
+
+.. autoclass:: zipline.algorithm.TradingAlgorithm
+
+Pipeline API
+~~~~~~~~~~~~
+
+.. autoclass:: zipline.pipeline.Pipeline
+   :members:
+   :member-order: groupwise
+
+.. autoclass:: zipline.pipeline.CustomFactor
+   :members:
+   :member-order: groupwise
+
+.. autoclass:: zipline.pipeline.factors.Factor
+   :members: top, bottom, rank, percentile_between, isnan, notnan, isfinite,
+             eq, __add__, __sub__, __mul__, __div__, __mod__, __pow__, __lt__,
+             __le__, __ne__, __ge__, __gt__
+   :exclude-members: dtype
+   :member-order: bysource
+
+.. autoclass:: zipline.pipeline.filters.Filter
+   :members: __and__, __or__
+   :exclude-members: dtype
+
+Asset Metadata
+~~~~~~~~~~~~~~
+
+.. autoclass:: zipline.assets.assets.Asset
+   :members:
+
+.. autoclass:: zipline.assets.assets.Equity
+   :members:
+
+.. autoclass:: zipline.assets.assets.Future
+   :members:
+
+.. autoclass:: zipline.assets.assets.AssetFinder
+   :members:
+
+.. autoclass:: zipline.assets.assets.AssetFinderCachedEquities
+   :members:
+
+.. autoclass:: zipline.assets.asset_writer.AssetDBWriter
+   :members:
+
+.. autoclass:: zipline.assets.assets.AssetConvertible
+   :members:

docs/source/conf.py

@@ -15,6 +15,7 @@ extensions = [
     'sphinx.ext.doctest',
     'sphinx.ext.extlinks',
     'sphinx.ext.autosummary',
+    'sphinx.ext.viewcode',
 ]
 
 

docs/source/releases.rst

@@ -2,6 +2,8 @@
 Release Notes
 =============
 
+.. include:: whatsnew/0.8.4.txt
+
 .. include:: whatsnew/0.8.3.txt
 
 .. include:: whatsnew/0.8.0.txt

docs/source/whatsnew/0.8.4.txt

@@ -1,9 +1,13 @@
-Release 0.8.4
--------------
+Development
+-----------
 
 :Release: 0.8.4
 :Date: TBD
 
+.. warning::
+   This release is still under active development.  All changes listed are
+   subject to change at any time.
+
 Highlights
 ~~~~~~~~~~
 
@@ -12,13 +16,18 @@ None
 Enhancements
 ~~~~~~~~~~~~
 
-* Adds a way for users to specify context manager to use when executing the
+* Adds a way for users to provide a context manager to use when executing the
   scheduled functions (including ``handle_data``). This context manager will be
   passed the :class:`~zipline.protocol.BarData` object for the bar and will
   be used for the duration of all of the functions scheduled to run. This can be
   passed to :class:`~zipline.algorithm.TradingAlgorithm` by the keyword argument
   ``create_event_context`` (:issue:`828`).
 
+* Added :meth:`~zipline.pipeline.factors.Factor.isnan`,
+  :meth:`~zipline.pipeline.factors.Factor.notnan` and
+  :meth:`~zipline.pipeline.factors.Factor.isfinite` methods to
+  :class:`zipline.pipeline.factors.Factor` (:issue:`861`).
+
 Experimental Features
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -38,10 +47,11 @@ Bug Fixes
 Performance
 ~~~~~~~~~~~
 
-* Speeds up `AssetFinder.lookup_symbol` by adding an extension, 
-`AssetFinderCachedEquities`, that loads equities into dictionaries and
-then directs `lookup_symbol` to these dictionaries to find matching equities
- (:issue:`830`).
+* Speeds up :meth:`~zipline.assets.assets.AssetFinder.lookup_symbol` by adding
+  an extension, :class:`~zipline.assets.assets.AssetFinderCachedEquities`, that
+  loads equities into dictionaries and then directs
+  :meth:`~zipline.assets.assets.AssetFinder.lookup_symbol` to these dictionaries
+  to find matching equities (:issue:`830`).
 
 Maintenance and Refactorings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -61,6 +71,10 @@ Documentation
 ~~~~~~~~~~~~~
 
 * Document the release process for developers (:issue:`835`).
+* Added reference docs for the Pipeline API. (:issue:`864`).
+* Added reference docs for Asset Metadata APIs. (:issue:`864`).
+* Generated documentation now includes links to source code for many classes
+  and functions. (:issue:`864`).
 
 Miscellaneous
 ~~~~~~~~~~~~~

zipline/assets/_assets.pyx

@@ -1,3 +1,4 @@
+# cython: embedsignature=True
 #
 # Copyright 2015 Quantopian, Inc.
 #

zipline/assets/assets.py

@@ -76,9 +76,25 @@ def _convert_asset_timestamp_fields(dict_):
 
 
 class AssetFinder(object):
+    """
+    An AssetFinder is an interface to a database of Asset metadata written by
+    an ``AssetDBWriter``.
 
+    This class provides methods for looking up assets by unique integer id or
+    by symbol.  For historical reasons, we refer to these unique ids as 'sids'.
+
+    Parameters
+    ----------
+    engine : str or SQLAlchemy.engine
+        An engine with a connection to the asset database to use, or a string
+        that can be parsed by SQLAlchemy as a URI.
+
+    See Also
+    --------
+    :class:`zipline.assets.asset_writer.AssetDBWriter`
+    """
     # Token used as a substitute for pickling objects that contain a
-    # reference to an AssetFinder
+    # reference to an AssetFinder.
     PERSISTENT_TOKEN = "<AssetFinder>"
 
     def __init__(self, engine):

zipline/pipeline/pipeline.py

@@ -17,7 +17,7 @@ class Pipeline(object):
     To compute a pipeline in the context of a TradingAlgorithm, users must call
     ``attach_pipeline`` in their ``initialize`` function to register that the
     pipeline should be computed each trading day.  The outputs of a pipeline on
-    a given day can be accessed by calling ``pipeline_outputs`` in
+    a given day can be accessed by calling ``pipeline_output`` in
     ``handle_data`` or ``before_trading_start``.
 
     Parameters