updates to docs

docs/conf.py

@@ -12,6 +12,9 @@
 
 
 master_doc = 'index'
+add_module_names = False
+default_role = 'py:obj'
+
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
 
@@ -22,6 +25,7 @@
     'http://zodb.readthedocs.org/en/latest/': None,
 }
 
+html_compact_lists = False
 html_static_path = ['_static']
 html_theme_path = ['_themes']
 html_theme = 'flask_small'

docs/index.rst

@@ -93,7 +93,7 @@ enough for demonstrative purposes and maybe for development.
 Using the ZODB from a Flask View
 --------------------------------
 
-This `db` object we set up functions like a normal Python dict that is
+This *db* object we set up functions like a normal Python dict that is
 persistent between requests and server restarts, independent of the user
 session and can be set up to propagate between multiple processes or over a
 network.  Requests in Flask are treated as a transaction that is committed
@@ -138,7 +138,7 @@ the request context is "popped":
 
 This can be useful in unit tests or from an interactive shell, or perhaps
 in a Flask-Script_ command.  Typically a test request context is already
-set up in these cases and you can just use `db` directly.
+set up in these cases and you can just use ``db`` directly.
 
 .. _Flask-Script: http://packages.python.org/Flask-Script/
 
@@ -172,9 +172,11 @@ API Reference
 
   Flask configuration option which must be set to one of:
 
-  * A URI string supported by zodburi_
-  * A tuple ``(storage_factory, db_keyword_args)``
-  * A callable ``storage_factory``
+  .. rst-class:: compact
+
+    * A URI string supported by zodburi_
+    * A tuple ``(storage_factory, db_keyword_args)``
+    * A callable ``storage_factory``
 
   .. _zodburi: https://docs.pylonsproject.org/projects/zodburi/dev/
 
@@ -190,29 +192,28 @@ balanced trees commonly used with ZODB.
 
 .. class:: Object
 
-  Alias of :class:`persistent.Persistent`.  Use this as the base class for
-  your plain objects instead of :func:`object`, if you intend to save
-  the object in ZODB.  This way changes to existing objects are detected
-  and saved automatically.
+  Alias of `persistent.Persistent`.  Use this as the base class for your
+  plain objects instead of `object`, if you intend to save the object in
+  ZODB.  This way changes to existing objects are detected and saved
+  automatically.
 
 .. class:: List
 
-  Alias of :class:`persistent.list.PersistentList`.  Use this instead of
-  :func:`list` for lists that you save in ZODB and changes to it will be
-  detected and saved automatically.  Not necessary if you won't be changing
-  the list after it is saved.
+  Alias of `persistent.list.PersistentList`.  Use this instead of `list`
+  for lists that you save in ZODB and changes to it will be detected and
+  saved automatically.  Not necessary if you won't be changing the list
+  after it is saved.
 
 .. class:: Dict
 
-  Alias of :class:`persistent.mapping.PersistentMapping`.  Use this
-  instead of :func:`dict` for mappings that you save in ZODB and that you
-  might want to make changes to later.  This way those changes will
-  automatically be detected and saved.
+  Alias of `persistent.mapping.PersistentMapping`.  Use this instead of
+  `dict` for mappings that you save in ZODB and that you might want to make
+  changes to later.  This way those changes will automatically be detected
+  and saved.
 
 .. class:: BTree
 
-  Alias of :class:`BTrees.OOBTree.OOBTree`.  Behaves mostly like
-  :class:`Dict` but requires that the keys are orderable and performs
-  better on large mappings.  Whereas a :class:`Dict` is fully loaded in
-  memory every time it is read, a BTree mapping only loads the items that
-  you try to read.
+  Alias of `BTrees.OOBTree.OOBTree`.  Behaves mostly like `Dict` but
+  requires that the keys are orderable and performs better on large
+  mappings.  Whereas a `Dict` is fully loaded in memory every time it is
+  read, a BTree mapping only loads the items that you try to read.

flaskext/zodb.py

@@ -18,7 +18,7 @@
 
 class ZODB(IterableUserDict):
     """Extension object.  Behaves as the root object of the storage during
-    requests, i.e. a :class:`~persistent.mapping.PersistentMapping`.
+    requests, i.e. a `~persistent.mapping.PersistentMapping`.
 
     ::
 
@@ -46,8 +46,8 @@ def init_app(self, app):
         app.teardown_request(self.close_db)
 
     def close_db(self, exception):
-        """Added as a :meth:`~flask.Flask.teardown_request` to applications
-        to commit the transaction and disconnect ZODB if it was used during
+        """Added as a `~flask.Flask.teardown_request` to applications to
+        commit the transaction and disconnect ZODB if it was used during
         the request."""
         if self.is_connected:
             if exception is None and not transaction.isDoomed():
@@ -57,7 +57,7 @@ def close_db(self, exception):
             self.connection.close()
 
     def create_db(self, app):
-        """Create a ZODB connection pool from the `app` configuration."""
+        """Create a ZODB connection pool from the *app* configuration."""
         assert 'ZODB_STORAGE' in app.config, \
                'ZODB_STORAGE not configured'
         storage = app.config['ZODB_STORAGE']