Added reference documentation

buildout.cfg

@@ -1,5 +1,5 @@
 [buildout]
-develop = .
+develop = . ../zodb
 parts =
     stxpy
     test
@@ -13,6 +13,9 @@ recipe = zc.recipe.egg
 eggs =
     Sphinx
     docutils
+    ZODB
+    j1m.sphinxautointerface
+
 interpreter = stxpy
 scripts =
     sphinx-build

conf.py

@@ -24,7 +24,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['sphinx.ext.autodoc', 'j1m.sphinxautointerface']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['.templates']

documentation/reference/index.rst

@@ -0,0 +1,11 @@
+=======================
+Reference Documentation
+=======================
+
+
+.. toctree::
+   :maxdepth: 2
+
+   zodb.rst
+   storages.rst
+

documentation/reference/storages.rst

@@ -0,0 +1,132 @@
+============
+Storage APIs
+============
+
+.. contents::
+
+Storage interfaces
+==================
+
+There are various storage implementations that implement standard
+storage interfaces. Thet differ primarily in their constructors.
+
+Application code rarely calls storage methods, and those it calls are
+generally called indirectly through databases.  There are
+interface-defined methods that are called internally by ZODB. These
+aren't shown below.
+
+
+IStorage
+--------
+
+.. autointerface:: ZODB.interfaces.IStorage
+   :members: close, getName, getSize, history, isReadOnly, lastTransaction,
+             __len__, pack, sortKey
+
+IStorageIteration
+-----------------
+
+.. autointerface:: ZODB.interfaces.IStorageIteration
+
+IStorageUndoable
+----------------
+
+.. autointerface:: ZODB.interfaces.IStorageUndoable
+   :members: undoLog, undoInfo
+
+IStorageCurrentRecordIteration
+------------------------------
+
+.. autointerface:: ZODB.interfaces.IStorageCurrentRecordIteration
+
+IBlobStorage
+------------
+
+.. autointerface:: ZODB.interfaces.IBlobStorage
+   :members: temporaryDirectory
+
+IStorageRecordInformation
+-------------------------
+
+.. autointerface:: ZODB.interfaces.IStorageRecordInformation
+
+IStorageTransactionInformation
+------------------------------
+
+.. autointerface:: ZODB.interfaces.IStorageTransactionInformation
+
+.. _included-storages-label:
+
+Included storages
+=================
+
+FileStorage
+-----------
+
+
+.. autoclass:: ZODB.FileStorage.FileStorage.FileStorage
+   :members: __init__
+
+
+.. autointerface:: ZODB.FileStorage.interfaces.IFileStoragePacker
+
+
+MappingStorage
+--------------
+
+.. autoclass:: ZODB.MappingStorage.MappingStorage
+   :members: __init__
+
+DemoStorage
+-----------
+
+.. autoclass:: ZODB.DemoStorage.DemoStorage
+   :members: __init__, push, pop
+
+Noteworthy non-included storages
+================================
+
+A number of important ZODB storages are distriubuted separately, including:
+
+RelStorage
+  `RelStorage <http://relstorage.readthedocs.io/en/latest/>`_
+  stores data in relational databases.  This is especially
+  useful when you have requirements or existing infrastructure for
+  storing data in relational databases.  Unlike the included storages,
+  multiple processes can share the same database.
+
+  For more imformation, see http://relstorage.readthedocs.io/en/latest/.
+
+ZEO
+  `ZEO <https://github.com/zopefoundation/ZEO>`_
+  is a client-server database implementation for ZODB.  To use
+  ZEO, you run a ZEO server, and use ZEO clients in your application.
+
+  For more imformation, see https://github.com/zopefoundation/ZEO.
+
+ZRS
+  `ZRS <https://github.com/zc/zrs>`_
+  provides replication from one database to another.  It's most
+  commonly used with ZEO.  With ZRS, you create a ZRS primary database
+  around a :class:`~ZODB.FileStorage.FileStorage.FileStorage` and in a
+  separate process, you creatre a ZRS secondary storage around any
+  :interface:`storage <ZODB.interfaces.IStorage>`. As transactions are
+  committed on the primary, they're copied asynchronously to
+  secondaries.
+
+  For more imformation, see https://github.com/zc/zrs.
+
+zlibstorage
+  `zlibstorage <https://pypi.python.org/pypi/zc.zlibstorage>`_
+  compresses database records using the compression
+  algorithm used by `gzip <http://www.gzip.org/>`_.
+
+  For more imformation, see https://pypi.python.org/pypi/zc.zlibstorage.
+
+beforestorage
+  `beforestorage <https://pypi.python.org/pypi/zc.beforestorage>`_
+  provides a point-in-time view of a database that might
+  be changing.  This can be useful to provide a non-changing view of a
+  production database for use with a :class:`~ZODB.DemoStorage.DemoStorage`.
+
+  For more imformation, see https://pypi.python.org/pypi/zc.beforestorage.

documentation/reference/zodb.rst

@@ -0,0 +1,96 @@
+=========
+ZODB APIs
+=========
+
+.. contents::
+
+ZODB module functions
+=====================
+
+.. method:: DB(storage, *args, **kw)
+
+      Create a databse. See :py:class:`ZODB.DB`.
+
+.. autofunction:: ZODB.connection
+
+Databases
+=========
+
+.. autoclass:: ZODB.DB
+   :members: __init__, open, close, pack,
+             cacheDetail, cacheExtremeDetail, cacheMinimize,
+             cacheSize, cacheDetailSize, getCacheSize, getCacheSizeBytes,
+             lastTransaction, getName, getPoolSize, getSize,
+             getHistoricalCacheSize, getHistoricalCacheSizeBytes,
+             getHistoricalPoolSize, getHistoricalTimeout,
+             objectCount, connectionDebugInfo,
+             setCacheSize, setCacheSizeBytes,
+             setHistoricalCacheSize, setHistoricalCacheSizeBytes,
+             setPoolSize, setHistoricalPoolSize, setHistoricalTimeout,
+             history,
+             supportsUndo, undoLog, undoInfo, undoMultiple, undo,
+             transaction, storage
+
+
+Connections
+===========
+
+.. autoclass:: ZODB.Connection.Connection
+   :members: add, cacheGC, cacheMinimize, close, db, get,
+             getDebugInfo, get_connection, isReadOnly, oldstate,
+             onCloseCallback, root, setDebugInfo, sync
+
+TimeStamp (transaction ids)
+===========================
+
+.. class:: ZODB.TimeStamp.TimeStamp(year, month, day, hour, minute, seconds)
+
+   Create a time-stamp object. Time stamps facilitate the computation
+   of transaction ids, which are based on times. The arguments are
+   integers, except for seconds, which may be a floating-point
+   number. Time stamps have microsecond precision. Time stamps are
+   implicitly UTC based.
+
+   Time stamps are orderable and hashable.
+
+   .. method:: day()
+
+      Return the time stamp's day.
+
+   .. method:: hour()
+
+      Return the time stamp's hour.
+
+   .. method:: laterThan(other)
+
+      Return a timestamp instance which is later than 'other'.
+
+      If self already qualifies, return self.
+
+      Otherwise, return a new instance one moment later than 'other'.
+
+   .. method:: minute()
+
+      Return the time stamp's minute.
+
+   .. method:: month()
+
+      Return the time stamp's month.
+
+   .. method:: raw()
+
+      Get an 8-byte representatin of the time stamp for use in APIs
+      that require a time stamp.
+
+   .. method:: second()
+
+      Return the time stamp's second.
+
+   .. method:: timeTime()
+
+      Return the time stamp as seconds since the epoc, as used by the
+      ``time`` module.
+
+   .. method:: year()
+
+      Return the time stamp's year.

index.rst

@@ -198,6 +198,7 @@ Learning more
 
    documentation/tutorial
    documentation/guide/index
+   documentation/reference/index
    documentation/articles/index
 
 * `The ZODB Book (in progress) <http://zodb.readthedocs.org/en/latest/>`_ 

requirements.txt

@@ -0,0 +1,4 @@
+Sphinx
+docutils
+ZODB
+j1m.sphinxautointerface