Added ZConfig configuration reference docs

buildout.cfg

@@ -15,6 +15,7 @@ eggs =
     docutils
     ZODB
     j1m.sphinxautointerface
+    j1m.sphinxautozconfig
 
 interpreter = stxpy
 scripts =

conf.py

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

documentation/reference/storages.rst

@@ -70,6 +70,18 @@ FileStorage
 
 .. autointerface:: ZODB.FileStorage.interfaces.IFileStoragePacker
 
+FileStorage text configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+File storages are configured using the ``filestorage`` section::
+
+  <filestorage>
+    path Data.fs
+  </filestorage>
+
+which accepts the following options:
+
+.. zconfigsectionkeys:: ZODB component.xml filestorage
 
 MappingStorage
 --------------
@@ -77,12 +89,56 @@ MappingStorage
 .. autoclass:: ZODB.MappingStorage.MappingStorage
    :members: __init__
 
+MappingStorage text configuration
+---------------------------------
+
+File storages are configured using the ``mappingstorage`` section::
+
+  <mappingstorage>
+  </mappingstorage>
+
+Options:
+
+.. zconfigsectionkeys:: ZODB component.xml mappingstorage
+
 DemoStorage
 -----------
 
 .. autoclass:: ZODB.DemoStorage.DemoStorage
    :members: __init__, push, pop
 
+DemoStorage text configuration
+------------------------------
+
+Demo storages are configured using the ``demostorage`` section::
+
+  <demostorage>
+    <filestorage base>
+      path base.fs
+    </filestorage>
+    <mappingstorage changes>
+      name Changes
+    </mappingstorage>
+  </demostorage>
+
+.. -> src
+
+   >>> import ZODB.config
+   >>> storage = ZODB.config.storageFromString(src)
+   >>> storage.base.getName()
+   'base.fs'
+   >>> storage.changes.getName()
+   'Changes'
+
+``demostorage`` sections can contain up to 2 storage subsections,
+named ``base`` and ``changes``, specifying the demo storage's base and
+changes storages.  See :meth:`ZODB.DemoStorage.DemoStorage.__init__`
+for more on the base anc changes storages.
+
+Options:
+
+.. zconfigsectionkeys:: ZODB component.xml demostorage
+
 Noteworthy non-included storages
 ================================
 
@@ -98,9 +154,10 @@ RelStorage
   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.
+  `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.  Unlike the included
+  storages, multiple processes can share the same database.
 
   For more imformation, see https://github.com/zopefoundation/ZEO.
 

documentation/reference/zodb.rst

@@ -31,6 +31,48 @@ Databases
              supportsUndo, undoLog, undoInfo, undoMultiple, undo,
              transaction, storage
 
+Database text configuration
+---------------------------
+
+Databases are configured with ``zodb`` sections::
+
+  <zodb>
+    cache-size-bytes 100MB
+    <mappingstorage
+    </mappingstorage>
+  </zodb>
+
+A ``zodb`` section must have a storage sub-section specifying a
+storage and any of the following options:
+
+.. zconfigsectionkeys:: ZODB component.xml zodb
+
+For a multi-database configuration, use multiple ``zodb`` sections and
+give the sections names::
+
+  <zodb first>
+    cache-size-bytes 100MB
+    <mappingstorage>
+    </mappingstorage>
+  </zodb>
+
+  <zodb second>
+    <mappingstorage>
+    </mappingstorage>
+  </zodb>
+
+.. -> src
+
+   >>> import ZODB.config
+   >>> db = ZODB.config.databaseFromString(src)
+   >>> sorted(db.databases)
+   ['first', 'second']
+   >>> db._cache_size_bytes
+   104857600
+
+When the configuration is loaded, a single database will be returned,
+but all of the databases will be available through the returned
+database's ``databases`` attribute.
 
 Connections
 ===========

zodbdocumentationtests/tests.py

@@ -34,11 +34,14 @@ def tearDown(test):
 def test_suite():
     here = os.path.dirname(__file__)
     guide = join(here, '..', 'documentation', 'guide')
+    reference = join(here, '..', 'documentation', 'reference')
 
     return unittest.TestSuite((
         manuel.testing.TestSuite(
             manuel.doctest.Manuel() + manuel.capture.Manuel(),
             join(guide, 'writing-persistent-objects.rst'),
+            join(reference, 'zodb.rst'),
+            join(reference, 'storages.rst'),
             setUp=setUp, tearDown=tearDown,
             ),
         ))