Merge lp:~cjwatson/storm/sphinx-doc into lp:storm

[Colin Watson]

Add Sphinx documentation.

This is loosely inspired by similar work done by Andreas Runfalk in https://github.com/runfalk/storm-legacy, although I made these changes independently (mainly because that fork also switches to pytest, which I didn't want to do).

I've converted the existing doctests to reStructuredText and integrated them as narrative documentation. They're still run as doctests.

[Ioana Lasc (ilasc)]

review: Approve

=== modified file '.bzrignore'
--- .bzrignore	2019-09-29 14:05:31 +0000
+++ .bzrignore	2020-05-26 10:31:46 +0000
@@ -13,6 +13,7 @@
 debian/python-storm.prerm.debhelper
 debian/python-storm.substvars
 apidoc
+storm/docs/_build
 .tox
 _trial_temp
 *.egg

=== modified file 'MANIFEST.in'
--- MANIFEST.in	2019-11-21 11:49:06 +0000
+++ MANIFEST.in	2020-05-26 10:31:46 +0000
@@ -1,5 +1,8 @@
-recursive-include storm *.py *.c *.zcml *.txt
+recursive-include storm *.py *.c *.zcml *.rst
 
 include MANIFEST.in LICENSE README TODO NEWS Makefile dev/test setup.cfg tox.ini
 
+include storm/docs/Makefile
+prune storm/docs/_build
+
 prune db

=== modified file 'NEWS'
--- NEWS	2020-05-19 09:02:51 +0000
+++ NEWS	2020-05-26 10:31:46 +0000
@@ -1,6 +1,11 @@
 0.24
 ====
 
+Improvements
+------------
+
+- Add Sphinx documentation.
+
 Bug fixes
 ---------
 

=== modified file 'README'
--- README	2019-11-21 11:29:33 +0000
+++ README	2020-05-26 10:31:46 +0000
@@ -59,7 +59,7 @@
 License
 =======
 
-Copyright (C) 2006-2009 Canonical, Ltd.  All contributions must have
+Copyright (C) 2006-2020 Canonical, Ltd.  All contributions must have
 copyright assigned to Canonical.
 
 This library is free software; you can redistribute it and/or

=== modified file 'setup.py'
--- setup.py	2020-04-25 15:52:01 +0000
+++ setup.py	2020-05-26 10:31:46 +0000
@@ -86,5 +86,12 @@
     install_requires=["six"],
     test_suite="storm.tests.find_tests",
     tests_require=tests_require,
-    extras_require={"test": tests_require},
+    extras_require={
+        "doc": [
+            "fixtures",  # so that storm.testing can be imported
+            "sphinx",
+            "sphinx-epytext",
+            ],
+        "test": tests_require,
+        },
     )

=== added directory 'storm/docs'
=== added file 'storm/docs/Makefile'
--- storm/docs/Makefile	1970-01-01 00:00:00 +0000
+++ storm/docs/Makefile	2020-05-26 10:31:46 +0000
@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

=== added file 'storm/docs/__init__.py'
=== added file 'storm/docs/api.rst'
--- storm/docs/api.rst	1970-01-01 00:00:00 +0000
+++ storm/docs/api.rst	2020-05-26 10:31:46 +0000
@@ -0,0 +1,150 @@
+API
+===
+.. contents:: :local:
+
+
+Locals
+------
+
+The following names are re-exported from ``storm.locals`` for convenience:
+
+* :py:class:`storm.base.Storm`
+* :py:func:`storm.database.create_database`
+* :py:class:`storm.exceptions.StormError`
+* :py:class:`storm.expr.And`
+* :py:class:`storm.expr.Asc`
+* :py:class:`storm.expr.Count`
+* :py:class:`storm.expr.Delete`
+* :py:class:`storm.expr.Desc`
+* :py:class:`storm.expr.In`
+* :py:class:`storm.expr.Insert`
+* :py:class:`storm.expr.Join`
+* :py:class:`storm.expr.Like`
+* :py:class:`storm.expr.Max`
+* :py:class:`storm.expr.Min`
+* :py:class:`storm.expr.Not`
+* :py:class:`storm.expr.Or`
+* :py:class:`storm.expr.SQL`
+* :py:class:`storm.expr.Select`
+* :py:class:`storm.expr.Update`
+* :py:class:`storm.info.ClassAlias`
+* :py:class:`storm.properties.Bool`
+* :py:class:`storm.properties.Bytes`
+* :py:class:`storm.properties.Date`
+* :py:class:`storm.properties.DateTime`
+* :py:class:`storm.properties.Decimal`
+* :py:class:`storm.properties.Enum`
+* :py:class:`storm.properties.Float`
+* :py:class:`storm.properties.Int`
+* :py:class:`storm.properties.JSON`
+* :py:class:`storm.properties.List`
+* :py:class:`storm.properties.Pickle`
+* :py:class:`storm.properties.Time`
+* :py:class:`storm.properties.TimeDelta`
+* :py:class:`storm.properties.UUID`
+* :py:class:`storm.properties.Unicode`
+* :py:class:`storm.references.Proxy`
+* :py:class:`storm.references.Reference`
+* :py:class:`storm.references.ReferenceSet`
+* :py:data:`storm.store.AutoReload`
+* :py:class:`storm.store.Store`
+* :py:class:`storm.xid.Xid`
+
+
+
+Store
+-----
+.. automodule:: storm.store
+.. autoclass:: storm.store.ResultSet
+.. autoclass:: storm.store.TableSet
+.. autodata:: storm.store.AutoReload
+   :annotation:
+
+Defining tables and columns
+---------------------------
+
+Base
+~~~~
+.. automodule:: storm.base
+
+Properties
+~~~~~~~~~~
+.. automodule:: storm.properties
+
+References
+~~~~~~~~~~
+.. automodule:: storm.references
+
+Variables
+~~~~~~~~~
+.. automodule:: storm.variables
+
+SQLObject emulation
+~~~~~~~~~~~~~~~~~~~
+.. automodule:: storm.sqlobject
+
+
+Expressions
+-----------
+.. automodule:: storm.expr
+
+
+Databases
+---------
+.. automodule:: storm.database
+
+PostgreSQL
+~~~~~~~~~~
+.. automodule:: storm.databases.postgres
+
+SQLite
+~~~~~~
+.. automodule:: storm.databases.sqlite
+
+Transaction identifiers
+~~~~~~~~~~~~~~~~~~~~~~~
+.. automodule:: storm.xid
+
+
+Hooks and events
+----------------
+
+Event
+~~~~~
+.. automodule:: storm.event
+
+Tracer
+~~~~~~
+.. automodule:: storm.tracer
+
+
+Miscellaneous
+-------------
+
+Cache
+~~~~~
+.. automodule:: storm.cache
+
+Exceptions
+~~~~~~~~~~
+.. automodule:: storm.exceptions
+
+Info
+~~~~~
+.. automodule:: storm.info
+
+Testing
+~~~~~~~
+.. automodule:: storm.testing
+
+Timezone
+~~~~~~~~
+.. automodule:: storm.tz
+
+URIs
+~~~~
+.. automodule:: storm.uri
+
+WSGI
+~~~~
+.. automodule:: storm.wsgi

=== added file 'storm/docs/conf.py'
--- storm/docs/conf.py	1970-01-01 00:00:00 +0000
+++ storm/docs/conf.py	2020-05-26 10:31:46 +0000
@@ -0,0 +1,197 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+# Import and document the pure-Python versions of things.
+os.environ['STORM_CEXTENSIONS'] = '0'
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Storm'
+copyright = '2006-2020, Canonical Ltd.'
+author = 'Gustavo Niemeyer'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = ''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Fix missing support for @ivar and @cvar.
+from sphinx_epytext.process_docstring import FIELDS
+FIELDS.append("cvar")
+FIELDS.append("ivar")
+
+# 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',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx_epytext',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Stormdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'Storm.tex', 'Storm Documentation',
+     'Gustavo Niemeyer', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'storm', 'Storm Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'Storm', 'Storm Documentation',
+     author, 'Storm', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+intersphinx_mapping = {'https://docs.python.org/3': None}
+
+# Sphinx 1.8+ prefers this to `autodoc_default_flags`. It's documented that
+# either True or None mean the same thing as just setting the flag, but
+# only None works in 1.8 (True works in 2.0)
+autodoc_default_options = {
+    'members': None,
+    'show-inheritance': None,
+}
+autodoc_member_order = 'bysource'
+autoclass_content = 'both'

=== added file 'storm/docs/index.rst'
--- storm/docs/index.rst	1970-01-01 00:00:00 +0000
+++ storm/docs/index.rst	2020-05-26 10:31:46 +0000
@@ -0,0 +1,25 @@
+.. Storm documentation master file, created by
+   sphinx-quickstart on Sat May 23 01:56:39 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Storm's documentation!
+=================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   tutorial
+   infoheritance
+   zope
+   api
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

=== renamed file 'storm/tests/infoheritance.txt' => 'storm/docs/infoheritance.rst'
--- storm/tests/infoheritance.txt	2020-05-26 10:31:46 +0000
+++ storm/docs/infoheritance.rst	2020-05-26 10:31:46 +0000
@@ -1,11 +1,5 @@
-This Storm document is included in Storm's source code at
-`storm/tests/infoheritance.txt` so that it can be tested and be kept
-up-to-date.
-
-<<TableOfContents>>
-
-
-==== Introduction ====
+Infoheritance
+=============
 
 Storm doesn't support classes that have columns in multiple tables.  This
 makes using inheritance rather difficult.  The infoheritance pattern described
@@ -13,40 +7,43 @@
 the problems Storm has with multi-table classes.
 
 
-==== Defining a sample model ====
+Defining a sample model
+-----------------------
 
 Let's consider an inheritance hierarchy to migrate to Storm.
 
-{{{#!python
-class Person(object):
-
-    def __init__(self, name):
-        self.name = name
-
-
-class SecretAgent(Person):
-
-    def __init__(self, name, passcode):
-        super(SecretAgent, self).__init__(name)
-        self.passcode = passcode
-
-
-class Teacher(Person):
-
-    def __init__(self, name, school):
-        super(Employee, self).__init__(name):
-        self.school = school
-}}}
-
-We want to use three tables to store data for these objects: `person`,
-`secret_agent` and `teacher`.  We can't simply convert instance attributes to
-Storm properties and add `__storm_table__` definitions because a single object
-may not have columns that come from more than one table.  We can't have
-`Teacher` getting it's `name` column from the `person` table and it's `school`
-column from the `teacher` table, for example.
-
-
-==== The infoheritance pattern ====
+.. code-block:: python
+
+    class Person(object):
+
+        def __init__(self, name):
+            self.name = name
+
+
+    class SecretAgent(Person):
+
+        def __init__(self, name, passcode):
+            super(SecretAgent, self).__init__(name)
+            self.passcode = passcode
+
+
+    class Teacher(Person):
+
+        def __init__(self, name, school):
+            super(Employee, self).__init__(name):
+            self.school = school
+
+We want to use three tables to store data for these objects: ``person``,
+``secret_agent`` and ``teacher``.  We can't simply convert instance
+attributes to Storm properties and add ``__storm_table__`` definitions
+because a single object may not have columns that come from more than one
+table.  We can't have ``Teacher`` getting its ``name`` column from the
+``person`` table and its ``school`` column from the ``teacher`` table, for
+example.
+
+
+The infoheritance pattern
+-------------------------
 
 The infoheritance pattern uses composition instead of inheritance to work
 around the multiple table limitation.  A base Storm class is used to represent
@@ -55,230 +52,223 @@
 provides the additional data and behaviour you'd normally implement in a
 subclass.  Following is the design from above converted to use the pattern.
 
-{{{#!python
->>> from storm.locals import Storm, Store, Int, Unicode, Reference
-
->>> person_info_types = {}
-
->>> def register_person_info_type(info_type, info_class):
-...     existing_info_class = person_info_types.get(info_type)
-...     if existing_info_class is not None:
-...         raise RuntimeError("%r has the same info_type of %r" %
-...                            (info_class, existing_info_class))
-...     person_info_types[info_type] = info_class
-...     info_class.info_type = info_type
-
-
->>> class Person(Storm):
-...
-...     __storm_table__ = "person"
-...
-...     id = Int(allow_none=False, primary=True)
-...     name = Unicode(allow_none=False)
-...     info_type = Int(allow_none=False)
-...     _info = None
-...
-...     def __init__(self, store, name, info_class, **kwargs):
-...         self.name = name
-...         self.info_type = info_class.info_type
-...         store.add(self)
-...         self._info = info_class(self, **kwargs)
-...
-...     @property
-...     def info(self):
-...         if self._info is not None:
-...             return self._info
-...         assert self.id is not None
-...         info_class = person_info_types[self.info_type]
-...         if not hasattr(info_class, "__storm_table__"):
-...             info = info_class.__new__(info_class)
-...             info.person = self
-...         else:
-...             info = Store.of(self).get(info_class, self.id)
-...         self._info = info
-...         return info
-
-
->>> class PersonInfo(object):
-...
-...     def __init__(self, person):
-...         self.person = person
-
-
->>> class StoredPersonInfo(PersonInfo):
-...
-...     person_id = Int(allow_none=False, primary=True)
-...     person = Reference(person_id, Person.id)
-
-
->>> class SecretAgent(StoredPersonInfo):
-...
-...     __storm_table__ = "secret_agent"
-...
-...     passcode = Unicode(allow_none=False)
-...
-...     def __init__(self, person, passcode=None):
-...         super(SecretAgent, self).__init__(person)
-...         self.passcode = passcode
-
-
->>> class Teacher(StoredPersonInfo):
-...
-...     __storm_table__ = "teacher"
-...
-...     school = Unicode(allow_none=False)
-...
-...     def __init__(self, person, school=None):
-...         super(Teacher, self).__init__(person)
-...         self.school = school
->>>
-}}}
-
-The pattern works by having a base class, `Person`, keep a reference to an
-info class, `PersonInfo`.  Info classes need to be registered so that `Person`
-can discover them and load them when necessary.  Note that info types have the
-same ID as their parent object.  This isn't strictly necessary, but it makes
-certain things easy, such as being able to look up info objects directly by ID
-when given a person object.  `Person` objects are required to be in a store to
-ensure that an ID is available and can used by the info class.
-
-
-==== Registering info classes ====
+.. doctest::
+
+    >>> from storm.locals import Storm, Store, Int, Unicode, Reference
+
+    >>> person_info_types = {}
+
+    >>> def register_person_info_type(info_type, info_class):
+    ...     existing_info_class = person_info_types.get(info_type)
+    ...     if existing_info_class is not None:
+    ...         raise RuntimeError("%r has the same info_type of %r" %
+    ...                            (info_class, existing_info_class))
+    ...     person_info_types[info_type] = info_class
+    ...     info_class.info_type = info_type
+
+
+    >>> class Person(Storm):
+    ...
+    ...     __storm_table__ = "person"
+    ...
+    ...     id = Int(allow_none=False, primary=True)
+    ...     name = Unicode(allow_none=False)
+    ...     info_type = Int(allow_none=False)
+    ...     _info = None
+    ...
+    ...     def __init__(self, store, name, info_class, **kwargs):
+    ...         self.name = name
+    ...         self.info_type = info_class.info_type
+    ...         store.add(self)
+    ...         self._info = info_class(self, **kwargs)
+    ...
+    ...     @property
+    ...     def info(self):
+    ...         if self._info is not None:
+    ...             return self._info
+    ...         assert self.id is not None
+    ...         info_class = person_info_types[self.info_type]
+    ...         if not hasattr(info_class, "__storm_table__"):
+    ...             info = info_class.__new__(info_class)
+    ...             info.person = self
+    ...         else:
+    ...             info = Store.of(self).get(info_class, self.id)
+    ...         self._info = info
+    ...         return info
+
+
+    >>> class PersonInfo(object):
+    ...
+    ...     def __init__(self, person):
+    ...         self.person = person
+
+
+    >>> class StoredPersonInfo(PersonInfo):
+    ...
+    ...     person_id = Int(allow_none=False, primary=True)
+    ...     person = Reference(person_id, Person.id)
+
+
+    >>> class SecretAgent(StoredPersonInfo):
+    ...
+    ...     __storm_table__ = "secret_agent"
+    ...
+    ...     passcode = Unicode(allow_none=False)
+    ...
+    ...     def __init__(self, person, passcode=None):
+    ...         super(SecretAgent, self).__init__(person)
+    ...         self.passcode = passcode
+
+
+    >>> class Teacher(StoredPersonInfo):
+    ...
+    ...     __storm_table__ = "teacher"
+    ...
+    ...     school = Unicode(allow_none=False)
+    ...
+    ...     def __init__(self, person, school=None):
+    ...         super(Teacher, self).__init__(person)
+    ...         self.school = school
+
+The pattern works by having a base class, ``Person``, keep a reference to an
+info class, ``PersonInfo``.  Info classes need to be registered so that
+``Person`` can discover them and load them when necessary.  Note that info
+types have the same ID as their parent object.  This isn't strictly
+necessary, but it makes certain things easy, such as being able to look up
+info objects directly by ID when given a person object.  ``Person`` objects
+are required to be in a store to ensure that an ID is available and can used
+by the info class.
+
+
+Registering info classes
+------------------------
 
 Let's register our info classes.  Each class must be registered with a unique
 info type key.  This key is stored in the database, so be sure to use a stable
 value.
 
-{{{#!python
->>> register_person_info_type(1, SecretAgent)
->>> register_person_info_type(2, Teacher)
->>>
-}}}
+.. doctest::
+
+    >>> register_person_info_type(1, SecretAgent)
+    >>> register_person_info_type(2, Teacher)
 
 Let's create a database to store person objects before we continue.
 
-{{{#!python
->>> from storm.locals import create_database
-
->>> database = create_database("sqlite:")
->>> store = Store(database)
->>> result = store.execute("""
-...     CREATE TABLE person (
-...         id INTEGER PRIMARY KEY,
-...         info_type INTEGER NOT NULL,
-...         name TEXT NOT NULL)
-... """)
->>> result = store.execute("""
-...     CREATE TABLE secret_agent (
-...         person_id INTEGER PRIMARY KEY,
-...         passcode TEXT NOT NULL)
-... """)
->>> result = store.execute("""
-...     CREATE TABLE teacher (
-...         person_id INTEGER PRIMARY KEY,
-...         school TEXT NOT NULL)
-... """)
->>>
-}}}
-
-
-==== Creating info classes ====
+.. doctest::
+
+    >>> from storm.locals import create_database
+
+    >>> database = create_database("sqlite:")
+    >>> store = Store(database)
+    >>> result = store.execute("""
+    ...     CREATE TABLE person (
+    ...         id INTEGER PRIMARY KEY,
+    ...         info_type INTEGER NOT NULL,
+    ...         name TEXT NOT NULL)
+    ... """)
+    >>> result = store.execute("""
+    ...     CREATE TABLE secret_agent (
+    ...         person_id INTEGER PRIMARY KEY,
+    ...         passcode TEXT NOT NULL)
+    ... """)
+    >>> result = store.execute("""
+    ...     CREATE TABLE teacher (
+    ...         person_id INTEGER PRIMARY KEY,
+    ...         school TEXT NOT NULL)
+    ... """)
+
+
+Creating info classes
+---------------------
 
 We can easily create person objects now.
 
-{{{#!python
->>> secret_agent = Person(store, u"Dick Tracy",
-...                       SecretAgent, passcode=u"secret!")
->>> teacher = Person(store, u"Mrs. Cohen",
-...                  Teacher, school=u"Cameron Elementary School")
->>> store.commit()
->>>
-}}}
+.. doctest::
+
+    >>> secret_agent = Person(store, u"Dick Tracy",
+    ...                       SecretAgent, passcode=u"secret!")
+    >>> teacher = Person(store, u"Mrs. Cohen",
+    ...                  Teacher, school=u"Cameron Elementary School")
+    >>> store.commit()
 
 And we can easily find them again.
 
-{{{#!python
->>> del secret_agent
->>> del teacher
->>> store.rollback()
-
->>> [type(person.info) for person in store.find(Person).order_by(Person.name)]
-[<class '...SecretAgent'>, <class '...Teacher'>]
->>>
-}}}
-
-
-==== Retrieving info classes ====
-
-Now that we have our basic hierarchy in place we're going to want to retrieve
-objects by info type.  Let's implement a function to make finding `Person`s
-easier.
-
-{{{#!python
->>> def get_persons(store, info_classes=None):
-...     where = []
-...     if info_classes:
-...         info_types = [info_class.info_type for info_class in info_classes]
-...         where = [Person.info_type.is_in(info_types)]
-...     result = store.find(Person, *where)
-...     result.order_by(Person.name)
-...     return result
-
->>> secret_agent = get_persons(store, info_classes=[SecretAgent]).one()
->>> print(secret_agent.name)
-Dick Tracy
->>> print(secret_agent.info.passcode)
-secret!
-
->>> teacher = get_persons(store, info_classes=[Teacher]).one()
->>> print(teacher.name)
-Mrs. Cohen
->>> print(teacher.info.school)
-Cameron Elementary School
-
->>>
-}}}
-
-Great, we can easily find different kinds of `Person`s.
-
-
-==== In-memory info objects ====
+.. doctest::
+
+    >>> del secret_agent
+    >>> del teacher
+    >>> store.rollback()
+
+    >>> [type(person.info)
+    ...  for person in store.find(Person).order_by(Person.name)]
+    [<class '...SecretAgent'>, <class '...Teacher'>]
+
+
+Retrieving info classes
+-----------------------
+
+Now that we have our basic hierarchy in place we're going to want to
+retrieve objects by info type.  Let's implement a function to make finding
+``Person``\ s easier.
+
+.. doctest::
+
+    >>> def get_persons(store, info_classes=None):
+    ...     where = []
+    ...     if info_classes:
+    ...         info_types = [
+    ...             info_class.info_type for info_class in info_classes]
+    ...         where = [Person.info_type.is_in(info_types)]
+    ...     result = store.find(Person, *where)
+    ...     result.order_by(Person.name)
+    ...     return result
+
+    >>> secret_agent = get_persons(store, info_classes=[SecretAgent]).one()
+    >>> print(secret_agent.name)
+    Dick Tracy
+    >>> print(secret_agent.info.passcode)
+    secret!
+
+    >>> teacher = get_persons(store, info_classes=[Teacher]).one()
+    >>> print(teacher.name)
+    Mrs. Cohen
+    >>> print(teacher.info.school)
+    Cameron Elementary School
+
+Great, we can easily find different kinds of ``Person``\ s.
+
+
+In-memory info objects
+----------------------
 
 This design also allows for in-memory info objects.  Let's add one to our
 hierarchy.
 
-{{{#!python
->>> class Ghost(PersonInfo):
-...
-...     friendly = True
-
->>> register_person_info_type(3, Ghost)
->>>
-}}}
+.. doctest::
+
+    >>> class Ghost(PersonInfo):
+    ...
+    ...     friendly = True
+
+    >>> register_person_info_type(3, Ghost)
 
 We create and load in-memory objects the same way we do stored ones.
 
-{{{#!python
->>> ghost = Person(store, u"Casper", Ghost)
->>> store.commit()
->>> del ghost
->>> store.rollback()
-
->>> ghost = get_persons(store, info_classes=[Ghost]).one()
->>> print(ghost.name)
-Casper
->>> print(ghost.info.friendly)
-True
-
->>>
-}}}
+.. doctest::
+
+    >>> ghost = Person(store, u"Casper", Ghost)
+    >>> store.commit()
+    >>> del ghost
+    >>> store.rollback()
+
+    >>> ghost = get_persons(store, info_classes=[Ghost]).one()
+    >>> print(ghost.name)
+    Casper
+    >>> print(ghost.info.friendly)
+    True
 
 This pattern is very handy when using Storm with code that would naturally be
 implemented using inheritance.
 
-
-==== Clean up ====
-
+..
     >>> Person._storm_property_registry.clear()
-
-## vim:ts=4:sw=4:et:ft=moin1_5

=== renamed file 'storm/tests/tutorial.txt' => 'storm/docs/tutorial.rst'
--- storm/tests/tutorial.txt	2020-05-26 10:31:46 +0000
+++ storm/docs/tutorial.rst	2020-05-26 10:31:46 +0000
@@ -1,154 +1,145 @@
-
-[[TableOfContents]]
-
-==== It runs! ====
-
-This Storm tutorial is included in the source code at
-storm/tests/tutorial.txt, so that it may be tested and stay
-up to date.
-
-
-==== Importing ====
+Tutorial
+========
+
+Importing
+---------
 
 Let's start by importing some names into the namespace.
 
-{{{#!python
->>> from storm.locals import *
->>>
-}}}
-
-==== Basic definition ====
+.. doctest::
+
+    >>> from storm.locals import *
+
+Basic definition
+----------------
 
 Now we define a type with some properties describing the information
 we're about to map.
 
-{{{#!python
->>> class Person(object):
-...     __storm_table__ = "person"
-...     id = Int(primary=True)
-...     name = Unicode()
+.. doctest::
 
-}}}
+    >>> class Person(object):
+    ...     __storm_table__ = "person"
+    ...     id = Int(primary=True)
+    ...     name = Unicode()
 
 Notice that this has no Storm-defined base class or constructor.
 
-==== Creating a database and the store ====
+Creating a database and the store
+---------------------------------
 
 We still don't have anyone to talk to, so let's define an in-memory
 SQLite database to play with, and a store using that database.
 
-{{{#!python
->>> database = create_database("sqlite:")
->>> store = Store(database)
->>>
-}}}
+.. doctest::
+
+    >>> database = create_database("sqlite:")
+    >>> store = Store(database)
 
 Two databases are supported at the moment: SQLite and PostgreSQL.
-The parameter passed to `create_database()` is an URI, as follows:
-
-{{{
-database = create_database("scheme://username:password@hostname:port/database_name")
-}}}
-
-The scheme may be "sqlite" or "postgres".
+The parameter passed to :py:func:`~storm.database.create_database` is an
+URI, as follows:
+
+.. code-block:: python
+
+    # database = create_database(
+    #     "scheme://username:password@hostname:port/database_name")
+
+The ``scheme`` may be ``sqlite`` or ``postgres``.
 
 Now we have to create the table that will actually hold the data
 for our class.
 
-{{{#!python
->>> store.execute("CREATE TABLE person "
-...               "(id INTEGER PRIMARY KEY, name VARCHAR)")
-<storm.databases.sqlite.SQLiteResult object at 0x...>
+.. doctest::
 
-}}}
+    >>> store.execute("CREATE TABLE person "
+    ...               "(id INTEGER PRIMARY KEY, name VARCHAR)")
+    <storm.databases.sqlite.SQLiteResult object at 0x...>
 
 We got a result back, but we don't care about it for now. We could also
-use `noresult=True` to avoid the result entirely.
+use ``noresult=True`` to avoid the result entirely.
 
-==== Creating an object ====
+Creating an object
+------------------
 
 Let's create an object of the defined class.
 
-{{{#!python
->>> joe = Person()
->>> joe.name = u"Joe Johnes"
-
->>> print(joe.id)
-None
->>> print(joe.name)
-Joe Johnes
-
-}}}
+.. doctest::
+
+    >>> joe = Person()
+    >>> joe.name = u"Joe Johnes"
+
+    >>> print(joe.id)
+    None
+    >>> print(joe.name)
+    Joe Johnes
 
 So far this object has no connection to a database. Let's add it to the
 store we've created above.
 
-{{{#!python
->>> store.add(joe)
-<...Person object at 0x...>
-
->>> print(joe.id)
-None
->>> print(joe.name)
-Joe Johnes
-
-}}}
+.. doctest::
+
+    >>> store.add(joe)
+    <...Person object at 0x...>
+
+    >>> print(joe.id)
+    None
+    >>> print(joe.name)
+    Joe Johnes
 
 Notice that the object wasn't changed, even after being added to the
 store.  That's because it wasn't flushed yet.
 
-==== The store of an object ====
+The store of an object
+----------------------
 
-Once an object is added to a store, or retrieved from a store, it's
+Once an object is added to a store, or retrieved from a store, its
 relation to that store is known.  We can easily verify which store
 an object is bound.
 
-{{{
->>> Store.of(joe) is store
-True
-
->>> Store.of(Person()) is None
-True
-
-}}}
-
-==== Finding an object ====
+.. doctest::
+
+    >>> Store.of(joe) is store
+    True
+
+    >>> Store.of(Person()) is None
+    True
+
+Finding an object
+-----------------
 
 Now, what would happen if we actually asked the store to give us
-the person named ''Joe Johnes''?
-
-{{{#!python
->>> person = store.find(Person, Person.name == u"Joe Johnes").one()
-
->>> print(person.id)
-1
->>> print(person.name)
-Joe Johnes
-
->>>
-}}}
+the person named "Joe Johnes"?
+
+.. doctest::
+
+    >>> person = store.find(Person, Person.name == u"Joe Johnes").one()
+
+    >>> print(person.id)
+    1
+    >>> print(person.name)
+    Joe Johnes
 
 The person is there!  Yeah, ok, you were expecting it. :-)
 
 We can also retrieve the object using its primary key.
 
-{{{#!python
->>> print(store.get(Person, 1).name)
-Joe Johnes
-
-}}}
-
-==== Caching behavior ====
+.. doctest::
+
+    >>> print(store.get(Person, 1).name)
+    Joe Johnes
+
+Caching behavior
+----------------
 
 One interesting thing is that this person is actually Joe, right? We've
 just added this object, so there's only one Joe, why would there be
 two different objects?  There isn't.
 
-{{{#!python
->>> person is joe
-True
+.. doctest::
 
-}}}
+    >>> person is joe
+    True
 
 What's going on behind the scenes is that each store has an object
 cache. When an object is linked to a store, it will be cached by
@@ -159,50 +150,52 @@
 will stay in memory inside the transaction, so that frequently used
 objects are not retrieved from the database too often.
 
-==== Flushing ====
+Flushing
+--------
 
 When we tried to find Joe in the database for the first time, we've
-noticed that the `id` property was magically assigned. This happened
+noticed that the ``id`` property was magically assigned. This happened
 because the object was flushed implicitly so that the operation would
 affect any pending changes as well.
 
 Flushes may also happen explicitly.
 
-{{{#!python
->>> mary = Person()
->>> mary.name = u"Mary Margaret"
->>> store.add(mary)
-<...Person object at 0x...>
-
->>> print(mary.id)
-None
->>> print(mary.name)
-Mary Margaret
-
->>> store.flush()
->>> print(mary.id)
-2
->>> print(mary.name)
-Mary Margaret
-
-}}}
-
-==== Changing objects with the Store ====
+.. doctest::
+
+    >>> mary = Person()
+    >>> mary.name = u"Mary Margaret"
+    >>> store.add(mary)
+    <...Person object at 0x...>
+
+    >>> print(mary.id)
+    None
+    >>> print(mary.name)
+    Mary Margaret
+
+    >>> store.flush()
+    >>> print(mary.id)
+    2
+    >>> print(mary.name)
+    Mary Margaret
+
+Changing objects with the Store
+-------------------------------
 
 Besides changing objects as usual, we can also benefit from the fact
 that objects are tied to a database to change them using expressions.
 
-{{{#!python
->>> store.find(Person, Person.name == u"Mary Margaret").set(name=u"Mary Maggie")
->>> print(mary.name)
-Mary Maggie
+.. doctest::
 
-}}}
+    >>> store.find(
+    ...     Person, Person.name == u"Mary Margaret").set(name=u"Mary Maggie")
+    >>> print(mary.name)
+    Mary Maggie
 
 This operation will touch every matching object in the database, and
 also objects that are alive in memory.
 
-==== Committing ====
+Committing
+----------
 
 Everything we've done so far is inside a transaction. At this point,
 we can either make these changes and any pending uncommitted changes
@@ -211,157 +204,150 @@
 
 We'll commit them, with something as simple as
 
-{{{#!python
->>> store.commit()
->>>
-}}}
+.. doctest::
+
+    >>> store.commit()
 
 That was straightforward. Everything is still the way it was, but now
 changes are there "for real".
 
-==== Rolling back ====
+Rolling back
+------------
 
 Aborting changes is very straightforward as well.
 
-{{{#!python
->>> joe.name = u"Tom Thomas"
->>>
-}}}
+.. doctest::
+
+    >>> joe.name = u"Tom Thomas"
 
 Let's see if these changes are really being considered by Storm
 and by the database.
 
-{{{#!python
->>> person = store.find(Person, Person.name == u"Tom Thomas").one()
->>> person is joe
-True
+.. doctest::
 
-}}}
+    >>> person = store.find(Person, Person.name == u"Tom Thomas").one()
+    >>> person is joe
+    True
 
 Yes, they are. Now, for the magic step (suspense music, please).
 
-{{{#!python
->>> store.rollback()
->>>
-}}}
+.. doctest::
+
+    >>> store.rollback()
 
 Erm.. nothing happened?
 
 Actually, something happened.. with Joe.  He's back!
 
-{{{#!python
->>> print(joe.id)
-1
->>> print(joe.name)
-Joe Johnes
-
-}}}
-
-==== Constructors ====
+.. doctest::
+
+    >>> print(joe.id)
+    1
+    >>> print(joe.name)
+    Joe Johnes
+
+Constructors
+------------
 
 So, we've been working for too long with people only. Let's introduce
 a new kind of data in our model: companies.  For the company, we'll
 use a constructor, just for the fun of it.  It will be the simplest
 company class you've ever seen:
 
-{{{#!python
->>> class Company(object):
-...     __storm_table__ = "company"
-...     id = Int(primary=True)
-...     name = Unicode()
-...
-...     def __init__(self, name):
-...         self.name = name
+.. doctest:
 
-}}}
+    >>> class Company(object):
+    ...     __storm_table__ = "company"
+    ...     id = Int(primary=True)
+    ...     name = Unicode()
+    ...
+    ...     def __init__(self, name):
+    ...         self.name = name
 
 Notice that the constructor parameter isn't optional.  It could be
 optional, if we wanted, but our companies always have names.
 
 Let's add the table for it.
 
-{{{#!python
->>> store.execute("CREATE TABLE company "
-...               "(id INTEGER PRIMARY KEY, name VARCHAR)", noresult=True)
+.. doctest::
 
-}}}
+    >>> store.execute(
+    ...     "CREATE TABLE company (id INTEGER PRIMARY KEY, name VARCHAR)",
+    ...     noresult=True)
 
 Then, create a new company.
 
-{{{
->>> circus = Company(u"Circus Inc.")
-
->>> print(circus.id)
-None
->>> print(circus.name)
-Circus Inc.
-
-}}}
-
-The `id` is still undefined because we haven't flushed it.  In fact,
-we haven't even '''added''' the company to the store.  We'll do
+.. doctest::
+
+    >>> circus = Company(u"Circus Inc.")
+
+    >>> print(circus.id)
+    None
+    >>> print(circus.name)
+    Circus Inc.
+
+The ``id`` is still undefined because we haven't flushed it.  In fact,
+we haven't even **added** the company to the store.  We'll do
 that soon.  Watch out.
 
 
-==== References and subclassing ====
+References and subclassing
+--------------------------
 
 Now we want to assign some employees to our company.  Rather than
 redoing the Person definition, we'll keep it as it is, since it's
 general, and will create a new subclass of it for employees, which
 include one extra field: the company id.
 
-{{{#!python
->>> class Employee(Person):
-...     __storm_table__ = "employee"
-...     company_id = Int()
-...     company = Reference(company_id, Company.id)
-...
-...     def __init__(self, name):
-...         self.name = name
-
-}}}
-
-Pay attention to that definiton for a moment. Notice that it doesn't
-define what's already in person, and introduces the `company_id`,
-and a `company` property, which is a reference to another class.  It
+.. doctest::
+
+    >>> class Employee(Person):
+    ...     __storm_table__ = "employee"
+    ...     company_id = Int()
+    ...     company = Reference(company_id, Company.id)
+    ...
+    ...     def __init__(self, name):
+    ...         self.name = name
+
+Pay attention to that definition for a moment. Notice that it doesn't
+define what's already in person, and introduces the ``company_id``,
+and a ``company`` property, which is a reference to another class.  It
 also has a constructor, but which leaves the company alone.
 
 As usual, we need a table.  SQLite has no idea of what a foreign key is,
 so we'll not bother to define it.
 
-{{{#!python
->>> store.execute("CREATE TABLE employee "
-...               "(id INTEGER PRIMARY KEY, name VARCHAR, company_id INTEGER)",
-...               noresult=True)
+.. doctest::
 
-}}}
+    >>> store.execute(
+    ...     "CREATE TABLE employee "
+    ...     "(id INTEGER PRIMARY KEY, name VARCHAR, company_id INTEGER)",
+    ...     noresult=True)
 
 Let's give life to Ben now.
 
-{{{#!python
->>> ben = store.add(Employee(u"Ben Bill"))
-
->>> print(ben.id)
-None
->>> print(ben.name)
-Ben Bill
->>> print(ben.company_id)
-None
-
-}}}
+.. doctest::
+
+    >>> ben = store.add(Employee(u"Ben Bill"))
+
+    >>> print(ben.id)
+    None
+    >>> print(ben.name)
+    Ben Bill
+    >>> print(ben.company_id)
+    None
 
 We can see that they were not flushed yet. Even then, we can say
 that Bill works on Circus.
 
-{{{#!python
->>> ben.company = circus
-
->>> print(ben.company_id)
-None
->>> print(ben.company.name)
-Circus Inc.
-
-}}}
+.. doctest::
+
+    >>> ben.company = circus
+
+    >>> print(ben.company_id)
+    None
+    >>> print(ben.company.name)
+    Circus Inc.
 
 Of course, we still don't know the company id since it was not
 flushed to the database yet, and we didn't assign an id explicitly.
@@ -371,15 +357,14 @@
 explicitly), objects will get their ids, and any references are
 updated as well (before being flushed!).
 
-{{{#!python
->>> store.flush()
-
->>> print(ben.company_id)
-1
->>> print(ben.company.name)
-Circus Inc.
-
-}}}
+.. doctest::
+
+    >>> store.flush()
+
+    >>> print(ben.company_id)
+    1
+    >>> print(ben.company.name)
+    Circus Inc.
 
 They're both flushed to the database.  Now, notice that the Circus
 company wasn't added to the store explicitly in any moment.  Storm
@@ -389,37 +374,34 @@
 Let's create another company to check something. This time we'll
 flush the store just after adding it.
 
-{{{#!python
->>> sweets = store.add(Company(u"Sweets Inc."))
->>> store.flush()
->>> sweets.id
-2
-
-}}}
-
+.. doctest::
+
+    >>> sweets = store.add(Company(u"Sweets Inc."))
+    >>> store.flush()
+    >>> sweets.id
+    2
 
 Nice, we've already got the id of the new company. So, what would
-happen if we changed '''just the id''' for Ben's company?
-
-{{{#!python
->>> ben.company_id = 2
->>> print(ben.company.name)
-Sweets Inc.
->>> ben.company is sweets
-True
-
-}}}
-
-Hah! '''That''' wasn't expected, was it? ;-)
+happen if we changed **just the id** for Ben's company?
+
+.. doctest::
+
+    >>> ben.company_id = 2
+    >>> print(ben.company.name)
+    Sweets Inc.
+    >>> ben.company is sweets
+    True
+
+Hah! **That** wasn't expected, was it? ;-)
 
 Let's commit everything.
 
-{{{#!python
->>> store.commit()
->>>
-}}}
-
-==== Many-to-one reference sets ====
+.. doctest::
+
+    >>> store.commit()
+
+Many-to-one reference sets
+--------------------------
 
 So, while our model says that employees work for a single company
 (we only design normal people here), companies may of course have
@@ -428,52 +410,48 @@
 We won't define the company again. Instead, we'll add a new attribute
 to the class.
 
-{{{#!python
->>> Company.employees = ReferenceSet(Company.id, Employee.company_id)
->>> 
-}}}
+.. doctest::
+
+    >>> Company.employees = ReferenceSet(Company.id, Employee.company_id)
 
 Without any further work, we can already see which employees are
 working for a given company.
 
-{{{#!python
->>> sweets.employees.count()
-1
-
->>> for employee in sweets.employees:
-...     print(employee.id)
-...     print(employee.name)
-...     print(employee is ben)
-...
-1
-Ben Bill
-True
-
-}}}
+.. doctest::
+
+    >>> sweets.employees.count()
+    1
+
+    >>> for employee in sweets.employees:
+    ...     print(employee.id)
+    ...     print(employee.name)
+    ...     print(employee is ben)
+    ...
+    1
+    Ben Bill
+    True
 
 Let's create another employee, and add him to the company, rather
 than setting the company in the employee (it sounds better, at least).
 
-{{{#!python
->>> mike = store.add(Employee(u"Mike Mayer"))
->>> sweets.employees.add(mike)
->>>
-}}}
+.. doctest::
+
+    >>> mike = store.add(Employee(u"Mike Mayer"))
+    >>> sweets.employees.add(mike)
 
 That, of course, means that Mike's working for a company, and so it
 should be reflected elsewhere.
 
-{{{#!python
->>> mike.company_id
-2
-
->>> mike.company is sweets
-True
-
-}}}
-
-
-==== Many-to-many reference sets and composed keys ====
+.. doctest::
+
+    >>> mike.company_id
+    2
+
+    >>> mike.company is sweets
+    True
+
+Many-to-many reference sets and composed keys
+---------------------------------------------
 
 We want to represent accountants in our model as well.  Companies have
 accountants, but accountants may also attend several companies, so we'll
@@ -482,19 +460,18 @@
 Let's create a simple class to use with accountants, and the relationship
 class.
 
-{{{#!python
->>> class Accountant(Person):
-...     __storm_table__ = "accountant"
-...     def __init__(self, name):
-...         self.name = name
-
->>> class CompanyAccountant(object):
-...     __storm_table__ = "company_accountant"
-...     __storm_primary__ = "company_id", "accountant_id"
-...     company_id = Int()
-...     accountant_id = Int()
-
-}}}
+.. doctest::
+
+    >>> class Accountant(Person):
+    ...     __storm_table__ = "accountant"
+    ...     def __init__(self, name):
+    ...         self.name = name
+
+    >>> class CompanyAccountant(object):
+    ...     __storm_table__ = "company_accountant"
+    ...     __storm_primary__ = "company_id", "accountant_id"
+    ...     company_id = Int()
+    ...     accountant_id = Int()
 
 Hey, we've just declared a class with a composed key!
 
@@ -503,44 +480,42 @@
 existent object.  It may easily be defined at class definition
 time.  Later we'll see another way to do that as well.
 
-{{{#!python
->>> Company.accountants = ReferenceSet(Company.id,
-...                                    CompanyAccountant.company_id,
-...                                    CompanyAccountant.accountant_id,
-...                                    Accountant.id)
+.. doctest::
 
-}}}
+    >>> Company.accountants = ReferenceSet(Company.id,
+    ...                                    CompanyAccountant.company_id,
+    ...                                    CompanyAccountant.accountant_id,
+    ...                                    Accountant.id)
 
 Done!  The order in which attributes were defined is important,
 but the logic should be pretty obvious.
 
 We're missing some tables, at this point.
 
-{{{#!python
->>> store.execute("CREATE TABLE accountant "
-...               "(id INTEGER PRIMARY KEY, name VARCHAR)", noresult=True)
-...
-
->>> store.execute("CREATE TABLE company_accountant "
-...               "(company_id INTEGER, accountant_id INTEGER,"
-...               " PRIMARY KEY (company_id, accountant_id))", noresult=True)
-
-}}}
-
+.. doctest::
+
+    >>> store.execute(
+    ...     "CREATE TABLE accountant (id INTEGER PRIMARY KEY, name VARCHAR)",
+    ...     noresult=True)
+
+    >>> store.execute(
+    ...     "CREATE TABLE company_accountant "
+    ...     "(company_id INTEGER, accountant_id INTEGER,"
+    ...     " PRIMARY KEY (company_id, accountant_id))",
+    ...     noresult=True)
 
 Let's give life to a couple of accountants, and register them
 in both companies.
 
-{{{#!python
->>> karl = Accountant(u"Karl Kent")
->>> frank = Accountant(u"Frank Fourt")
-
->>> sweets.accountants.add(karl)
->>> sweets.accountants.add(frank)
-
->>> circus.accountants.add(frank)
->>>
-}}}
+.. doctest::
+
+    >>> karl = Accountant(u"Karl Kent")
+    >>> frank = Accountant(u"Frank Fourt")
+
+    >>> sweets.accountants.add(karl)
+    >>> sweets.accountants.add(frank)
+
+    >>> circus.accountants.add(frank)
 
 That's it! Really!  Notice that we didn't even have to add them to
 the store, since it happens implicitly by linking to the other object
@@ -549,49 +524,47 @@
 
 We can now check them.
 
-{{{
->>> sweets.accountants.count()
-2
-
->>> circus.accountants.count()
-1
-
-}}}
-
-Even though we didn't use the Company``Accountant object explicitly,
+.. doctest::
+
+    >>> sweets.accountants.count()
+    2
+
+    >>> circus.accountants.count()
+    1
+
+Even though we didn't use the ``CompanyAccountant`` object explicitly,
 we can check it if we're really curious.
 
-{{{#!python
->>> store.get(CompanyAccountant, (sweets.id, frank.id))
-<...CompanyAccountant object at 0x...>
-
-}}}
-
-Notice that we pass a tuple for the `get()` method, due to the
-composed key.
+.. doctest::
+
+    >>> store.get(CompanyAccountant, (sweets.id, frank.id))
+    <...CompanyAccountant object at 0x...>
+
+Notice that we pass a tuple for the :py:meth:`~storm.store.Store.get`
+method, due to the composed key.
 
 If we wanted to know for which companies accountants are working,
 we could easily define a reversed relationship:
 
-{{{#!python
->>> Accountant.companies = ReferenceSet(Accountant.id,
-...                                     CompanyAccountant.accountant_id,
-...                                     CompanyAccountant.company_id,
-...                                     Company.id)
-
->>> for name in sorted(company.name for company in frank.companies):
-...     print(name)
-Circus Inc.
-Sweets Inc.
-
->>> for company in karl.companies:
-...     print(company.name)
-Sweets Inc.
-
-}}}
-
-
-==== Joins ====
+.. doctest::
+
+    >>> Accountant.companies = ReferenceSet(Accountant.id,
+    ...                                     CompanyAccountant.accountant_id,
+    ...                                     CompanyAccountant.company_id,
+    ...                                     Company.id)
+
+    >>> for name in sorted(company.name for company in frank.companies):
+    ...     print(name)
+    Circus Inc.
+    Sweets Inc.
+
+    >>> for company in karl.companies:
+    ...     print(company.name)
+    Sweets Inc.
+
+
+Joins
+-----
 
 Since we've got some nice data to play with, let's try to make a
 few interesting queries.
@@ -601,209 +574,204 @@
 
 First, with an implicit join.
 
-{{{#!python
->>> result = store.find(Company,
-...                     Employee.company_id == Company.id,
-...                     Employee.name.like(u"Ben %"))
-...
-
->>> for company in result:
-...     print(company.name)
-Sweets Inc.
-
-}}}
+.. doctest::
+
+    >>> result = store.find(Company,
+    ...                     Employee.company_id == Company.id,
+    ...                     Employee.name.like(u"Ben %"))
+
+    >>> for company in result:
+    ...     print(company.name)
+    Sweets Inc.
 
 Then, we can also do an explicit join.  This is interesting for mapping
 complex SQL joins to Storm queries.
 
-{{{#!python
->>> origin = [Company, Join(Employee, Employee.company_id == Company.id)]
->>> result = store.using(*origin).find(Company, Employee.name.like(u"Ben %"))
-
->>> for company in result:
-...     print(company.name)
-Sweets Inc.
-
-}}}
-
+.. doctest::
+
+    >>> origin = [Company, Join(Employee, Employee.company_id == Company.id)]
+    >>> result = store.using(*origin).find(
+    ...     Company, Employee.name.like(u"Ben %"))
+
+    >>> for company in result:
+    ...     print(company.name)
+    Sweets Inc.
 
 If we already had the company, and wanted to know which of his employees
 were named Ben, that'd have been easier.
 
-{{{#!python
->>> result = sweets.employees.find(Employee.name.like(u"Ben %"))
-
->>> for employee in result:
-...     print(employee.name)
-Ben Bill
-
-}}}
-
-
-==== Sub-selects ====
+.. doctest::
+
+    >>> result = sweets.employees.find(Employee.name.like(u"Ben %"))
+
+    >>> for employee in result:
+    ...     print(employee.name)
+    Ben Bill
+
+
+Sub-selects
+-----------
 
 Suppose we want to find all accountants that aren't associated with a
 company.  We can use a sub-select to get the data we want.
 
-{{{#!python
->>> laura = Accountant(u"Laura Montgomery")
->>> store.add(laura)
-<...Accountant ...>
-
->>> subselect = Select(CompanyAccountant.accountant_id, distinct=True)
->>> result = store.find(Accountant, Not(Accountant.id.is_in(subselect)))
->>> result.one() is laura
-True
->>>
-}}}
-
-
-==== Ordering and limiting results ====
+.. doctest::
+
+    >>> laura = Accountant(u"Laura Montgomery")
+    >>> store.add(laura)
+    <...Accountant ...>
+
+    >>> subselect = Select(CompanyAccountant.accountant_id, distinct=True)
+    >>> result = store.find(Accountant, Not(Accountant.id.is_in(subselect)))
+    >>> result.one() is laura
+    True
+
+
+Ordering and limiting results
+-----------------------------
 
 Ordering and limiting results obtained are certainly among the
 simplest and yet most wanted features for such tools, so we want
 to make them very easy to understand and use, of course.
 
-A code of line is worth a thousand words, so here are a few examples
+A line of code is worth a thousand words, so here are a few examples
 that demonstrate how it works:
 
-{{{
->>> garry = store.add(Employee(u"Garry Glare"))
-
->>> result = store.find(Employee)
-
->>> for employee in result.order_by(Employee.name):
-...     print(employee.name)
-Ben Bill
-Garry Glare
-Mike Mayer
-
->>> for employee in result.order_by(Desc(Employee.name)):
-...     print(employee.name)
-Mike Mayer
-Garry Glare
-Ben Bill
-
->>> for employee in result.order_by(Employee.name)[:2]:
-...     print(employee.name)
-Ben Bill
-Garry Glare
-
-}}}
-
-
-==== Multiple types with one query ====
+.. doctest::
+
+    >>> garry = store.add(Employee(u"Garry Glare"))
+
+    >>> result = store.find(Employee)
+
+    >>> for employee in result.order_by(Employee.name):
+    ...     print(employee.name)
+    Ben Bill
+    Garry Glare
+    Mike Mayer
+
+    >>> for employee in result.order_by(Desc(Employee.name)):
+    ...     print(employee.name)
+    Mike Mayer
+    Garry Glare
+    Ben Bill
+
+    >>> for employee in result.order_by(Employee.name)[:2]:
+    ...     print(employee.name)
+    Ben Bill
+    Garry Glare
+
+
+Multiple types with one query
+-----------------------------
 
 Sometimes, it may be interesting to retrieve more than one object involved
 in a given query.  Imagine, for instance, that besides knowing which
 companies have an employee named Ben, we also want to know who is the
 employee.  This may be achieved with a query like follows:
 
-{{{#!python
->>> result = store.find((Company, Employee),
-...                     Employee.company_id == Company.id,
-...                     Employee.name.like(u"Ben %"))
-
->>> for company, employee in result:
-...     print(company.name)
-...     print(employee.name)
-Sweets Inc.
-Ben Bill
-
-}}}
-
-
-==== The Storm base class ====
+.. doctest::
+
+    >>> result = store.find((Company, Employee),
+    ...                     Employee.company_id == Company.id,
+    ...                     Employee.name.like(u"Ben %"))
+
+    >>> for company, employee in result:
+    ...     print(company.name)
+    ...     print(employee.name)
+    Sweets Inc.
+    Ben Bill
+
+
+The Storm base class
+--------------------
 
 So far we've been defining our references and reference sets using
 classes and their properties.  This has some advantages, like being
 easier to debug, but also has some disadvantages, such as requiring
-classes to be present in the local scope, what potentially leads to
+classes to be present in the local scope, which potentially leads to
 circular import issues.
 
 To prevent that kind of situation, Storm supports defining these
 references using the stringified version of the class and property
 names.  The only inconvenience of doing so is that all involved
-classes must inherit from the `Storm` base class.
+classes must inherit from the :py:class:`~storm.base.Storm` base class.
 
 Let's define some new classes to show that.  To expose the point,
 we'll refer to a class before it's actually defined.
 
-{{{#!python
->>> class Country(Storm):
-...     __storm_table__ = "country"
-...     id = Int(primary=True)
-...     name = Unicode()
-...     currency_id = Int()
-...     currency = Reference(currency_id, "Currency.id")
-
->>> class Currency(Storm):
-...     __storm_table__ = "currency"
-...     id = Int(primary=True)
-...     symbol = Unicode()
-
->>> store.execute("CREATE TABLE country "
-...               "(id INTEGER PRIMARY KEY, name VARCHAR, currency_id INTEGER)",
-...               noresult=True)
-
->>> store.execute("CREATE TABLE currency "
-...               "(id INTEGER PRIMARY KEY, symbol VARCHAR)", noresult=True)
-
-}}}
-
+.. doctest::
+
+    >>> class Country(Storm):
+    ...     __storm_table__ = "country"
+    ...     id = Int(primary=True)
+    ...     name = Unicode()
+    ...     currency_id = Int()
+    ...     currency = Reference(currency_id, "Currency.id")
+
+    >>> class Currency(Storm):
+    ...     __storm_table__ = "currency"
+    ...     id = Int(primary=True)
+    ...     symbol = Unicode()
+
+    >>> store.execute(
+    ...     "CREATE TABLE country "
+    ...     "(id INTEGER PRIMARY KEY, name VARCHAR, currency_id INTEGER)",
+    ...     noresult=True)
+
+    >>> store.execute(
+    ...     "CREATE TABLE currency (id INTEGER PRIMARY KEY, symbol VARCHAR)",
+    ...     noresult=True)
 
 Now, let's see if it works.
 
-{{{#!python
->>> real = store.add(Currency())
->>> real.id = 1
->>> real.symbol = u"BRL"
-
->>> brazil = store.add(Country())
->>> brazil.name = u"Brazil"
->>> brazil.currency_id = 1
-
->>> print(brazil.currency.symbol)
-BRL
-
-}}}
+.. doctest::
+
+    >>> real = store.add(Currency())
+    >>> real.id = 1
+    >>> real.symbol = u"BRL"
+
+    >>> brazil = store.add(Country())
+    >>> brazil.name = u"Brazil"
+    >>> brazil.currency_id = 1
+
+    >>> print(brazil.currency.symbol)
+    BRL
 
 Questions!? ;-)
 
 
-==== Loading hook ====
+Loading hook
+------------
 
 Storm allows classes to define a few different hooks are called
 to act when certain things happen.  One of the interesting hooks
-available is the `__storm_loaded__` one.
+available is the ``__storm_loaded__`` one.
 
 Let's play with it.  We'll define a temporary subclass of Person
 for that.
 
-{{{#!python
->>> class PersonWithHook(Person):
-...     def __init__(self, name):
-...         print("Creating %s" % name)
-...         self.name = name
-...
-...     def __storm_loaded__(self):
-...         print("Loaded %s" % self.name)
-
-
->>> earl = store.add(PersonWithHook(u"Earl Easton"))
-Creating Earl Easton
-
->>> earl = store.find(PersonWithHook, name=u"Earl Easton").one()
-
->>> store.invalidate(earl)
->>> del earl
->>> import gc
->>> collected = gc.collect()
-
->>> earl = store.find(PersonWithHook, name=u"Earl Easton").one()
-Loaded Earl Easton
-
-}}}
+.. doctest::
+
+    >>> class PersonWithHook(Person):
+    ...     def __init__(self, name):
+    ...         print("Creating %s" % name)
+    ...         self.name = name
+    ...
+    ...     def __storm_loaded__(self):
+    ...         print("Loaded %s" % self.name)
+
+    >>> earl = store.add(PersonWithHook(u"Earl Easton"))
+    Creating Earl Easton
+
+    >>> earl = store.find(PersonWithHook, name=u"Earl Easton").one()
+
+    >>> store.invalidate(earl)
+    >>> del earl
+    >>> import gc
+    >>> collected = gc.collect()
+
+    >>> earl = store.find(PersonWithHook, name=u"Earl Easton").one()
+    Loaded Earl Easton
 
 Note that in the first find, nothing was called, since the object
 was still in memory and cached.  Then, we invalidated the object
@@ -813,52 +781,53 @@
 called (and not the constructor!).
 
 
-==== Executing expressions ====
+Executing expressions
+---------------------
 
 Storm also offers a way to execute expressions in a
 database-agnostic way, when that's necessary.
 
 For instance:
 
-{{{#!python
->>> result = store.execute(Select(Person.name, Person.id == 1))
->>> (name,) = result.get_one()
->>> print(name)
-Joe Johnes
+.. doctest::
 
-}}}
+    >>> result = store.execute(Select(Person.name, Person.id == 1))
+    >>> (name,) = result.get_one()
+    >>> print(name)
+    Joe Johnes
 
 This mechanism is used internally by Storm itself to implement
 the higher level features.
 
 
-==== Auto-reloading values ====
+Auto-reloading values
+---------------------
 
 Storm offers some special values that may be assigned to attributes
-under its control.  One of these values is `AutoReload`.  When used,
-it will make the object automatically reload the value from the
-database when touched.  Even primary keys may benefit from its use,
-as shown below.
-
-{{{
->>> from storm.locals import AutoReload
-
->>> ruy = store.add(Person())
->>> ruy.name = u"Ruy"
->>> print(ruy.id)
-None
-
->>> ruy.id = AutoReload
->>> print(ruy.id)
-4
-
-}}}
+under its control.  One of these values is
+:py:data:`~storm.store.AutoReload`.  When used, it will make the
+object automatically reload the value from the database when touched.
+Even primary keys may benefit from its use, as shown below.
+
+.. doctest::
+
+    >>> from storm.locals import AutoReload
+
+    >>> ruy = store.add(Person())
+    >>> ruy.name = u"Ruy"
+    >>> print(ruy.id)
+    None
+
+    >>> ruy.id = AutoReload
+    >>> print(ruy.id)
+    4
 
 This may be set as the default value for any attribute, making the
 object be automatically flushed if necessary.
 
 
-==== Expression values ====
+Expression values
+-----------------
 
 Besides auto-reloading, it's also possible to assign what we call
 a "lazy expression" to an attribute.  Such expressions are flushed
@@ -867,60 +836,57 @@
 
 For instance:
 
-{{{#!python
-from storm.locals import SQL
-
->>> ruy.name = SQL("(SELECT name || ? FROM person WHERE id=4)", (" Ritcher",))
->>> print(ruy.name)
-Ruy Ritcher
-
-}}}
-
-Notice that this is just an example of what '''may''' be done.  There's
+.. doctest::
+
+    >>> ruy.name = SQL(
+    ...     "(SELECT name || ? FROM person WHERE id=4)", (" Ritcher",))
+    >>> print(ruy.name)
+    Ruy Ritcher
+
+Notice that this is just an example of what **may** be done.  There's
 no need to write SQL statements this way, if you don't want to.  You may
 also use class-based SQL expressions provided in Storm, or even
 not use lazy expressions at all.
 
 
-==== Aliases ====
+Aliases
+-------
 
 So now let's say that we want to find every pair of people that work
-for the same company.  I have no idea about why one would ''want'' to
+for the same company.  I have no idea about why one would *want* to
 do that, but that's a good case for us to exercise aliases.
 
-First, we import `ClassAlias` into the local namespace (''mental note:
-this should be in storm.locals as well''), and create a reference to it.
-
-{{{#!python
->>> from storm.info import ClassAlias
->>> AnotherEmployee = ClassAlias(Employee)
-
-}}}
+First, we create an alias for the `Employee` class.
+
+.. doctest::
+
+    >>> from storm.info import ClassAlias
+    >>> AnotherEmployee = ClassAlias(Employee)
 
 Nice, isn't it?
 
 Now we can easily make the query we want, in a straightforward way:
 
-{{{#!python
->>> result = store.find((Employee, AnotherEmployee),
-...                     Employee.company_id == AnotherEmployee.company_id,
-...                     Employee.id > AnotherEmployee.id)
-
->>> for employee1, employee2 in result:
-...     print(employee1.name)
-...     print(employee2.name)
-Mike Mayer
-Ben Bill
-
-}}}
+.. doctest::
+
+    >>> result = store.find((Employee, AnotherEmployee),
+    ...                     Employee.company_id == AnotherEmployee.company_id,
+    ...                     Employee.id > AnotherEmployee.id)
+
+    >>> for employee1, employee2 in result:
+    ...     print(employee1.name)
+    ...     print(employee2.name)
+    Mike Mayer
+    Ben Bill
 
 Woah!  Mike and Ben work for the same company!
 
-(Quiz for the attent reader: why is ''greater than'' being used in
+(Quiz for the attentive reader: why is *greater than* being used in
 the query above?)
 
 
-==== Debugging ====
+Debugging
+---------
 
 Sometimes you just need to see which statements Storm is executing.  A
 debug tracer built on top of Storm's tracing system can be used to see
@@ -930,37 +896,33 @@
 provided.  Statements are logged to sys.stderr by default, but a
 custom stream may also be used.
 
-{{{#!python
->>> import sys
->>> from storm.tracer import debug
-
->>> debug(True, stream=sys.stdout)
->>> result = store.find((Employee, AnotherEmployee),
-...                     Employee.company_id == AnotherEmployee.company_id,
-...                     Employee.id > AnotherEmployee.id)
->>> list(result)
-[...] EXECUTE: ...'SELECT employee.company_id, employee.id, employee.name, "...".company_id, "...".id, "...".name FROM employee, employee AS "..." WHERE employee.company_id = "...".company_id AND employee.id > "...".id', ()
-[...] DONE
-[(<...Employee object at ...>, <...Employee object at ...>)]
-
->>> debug(False)
->>> list(result)
-[(<...Employee object at ...>, <...Employee object at ...>)]
-
-}}}
-
-
-==== Much more! ====
+.. doctest::
+
+    >>> import sys
+    >>> from storm.tracer import debug
+
+    >>> debug(True, stream=sys.stdout)
+    >>> result = store.find((Employee, AnotherEmployee),
+    ...                     Employee.company_id == AnotherEmployee.company_id,
+    ...                     Employee.id > AnotherEmployee.id)
+    >>> list(result)
+    [...] EXECUTE: ...'SELECT employee.company_id, employee.id, employee.name, "...".company_id, "...".id, "...".name FROM employee, employee AS "..." WHERE employee.company_id = "...".company_id AND employee.id > "...".id', ()
+    [...] DONE
+    [(<...Employee object at ...>, <...Employee object at ...>)]
+
+    >>> debug(False)
+    >>> list(result)
+    [(<...Employee object at ...>, <...Employee object at ...>)]
+
+
+Much more!
+----------
 
 There's a lot more about Storm to be shown.  This tutorial is just a
-way to get initiated on some of the concepts.  While your questions
-are not answered somewhere else, feel free to ask them in the mailing
+way to get initiated on some of the concepts.  If your questions are
+not answered somewhere else, feel free to ask them in the mailing
 list.
 
-
-==== Clean up ====
-
+..
     >>> Currency._storm_property_registry.clear()
     >>> Country._storm_property_registry.clear()
-
-## vim:ts=4:sw=4:et:ft=moin1_5

=== renamed file 'storm/tests/zope/README.txt' => 'storm/docs/zope.rst'
--- storm/tests/zope/README.txt	2020-05-26 10:31:46 +0000
+++ storm/docs/zope.rst	2020-05-26 10:31:46 +0000
@@ -1,31 +1,38 @@
-Copyright (c) 2006, 2007 Canonical
-
-Written by Jamshed Kakar <[e-mail]>
-
-This file is part of Storm Object Relational Mapper.
-
-Storm is free software; you can redistribute it and/or modify
-it under the terms of the GNU Lesser General Public License as
-published by the Free Software Foundation; either version 2.1 of
-the License, or (at your option) any later version.
-
-Storm is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Lesser General Public License for more details.
-
-You should have received a copy of the GNU Lesser General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-
-Introduction
-------------
-
-The storm.zope package contains the ZStorm utility which provides
+..
+    Copyright (c) 2006, 2007 Canonical
+
+    Written by Jamshed Kakar <[e-mail]>
+
+    This file is part of Storm Object Relational Mapper.
+
+    Storm is free software; you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as
+    published by the Free Software Foundation; either version 2.1 of
+    the License, or (at your option) any later version.
+
+    Storm is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+Zope integration
+================
+
+The ``storm.zope`` package contains the ZStorm utility which provides
 seamless integration between Storm and Zope 3's transaction system.
 Setting up ZStorm is quite easy.  In most cases, you want to include
-storm/zope/configure.zcml in your application.  For the purposes of
-this doctest we'll register ZStorm manually.
+``storm/zope/configure.zcml`` in your application, which you would normally
+do in ZCML as follows:
+
+.. code-block:: xml
+
+  <include package="storm.zope" />
+
+For the purposes of this doctest we'll register ZStorm manually.
 
   >>> from zope.component import provideUtility, getUtility
   >>> import transaction
@@ -48,8 +55,8 @@
   >>> zstorm.set_default_uri("test", "sqlite:")
 
 Setting a default URI for stores isn't strictly required.  We could
-pass it as the second argument to zstorm.get.  Providing a default URI
-makes it possible to use zstorm.get more easily; this is especially
+pass it as the second argument to ``zstorm.get``.  Providing a default URI
+makes it possible to use ``zstorm.get`` more easily; this is especially
 handy when multiple threads are used as we'll see further on.
 
   >>> store = zstorm.get("test")
@@ -97,7 +104,7 @@
   ... """)
   >>> store.commit()
 
-We'll need a Person class to use with this database.
+We'll need a ``Person`` class to use with this database.
 
   >>> from storm.locals import Storm, Int, Unicode
 
@@ -118,7 +125,7 @@
   <...Person object at ...>
   >>> transaction.commit()
 
-Notice that we're not using store.commit directly; we're using Zope's
+Notice that we're not using ``store.commit`` directly; we're using Zope's
 transaction system.  Let's make sure it worked.
 
   >>> store.rollback()
@@ -137,7 +144,7 @@
   >>> store.add(Person(u"Imposter!"))
   <...Person object at ...>
 
-At this point a store.find should return the new object.
+At this point a ``store.find`` should return the new object.
 
   >>> for name in sorted(person.name for person in store.find(Person)):
   ...     print(name)
@@ -145,7 +152,7 @@
   John Doe
 
 All this means is that the data has been flushed to the database; it's
-still not committed.  If we abort the transaction the new Person
+still not committed.  If we abort the transaction the new ``Person``
 object should disappear.
 
   >>> transaction.abort()
@@ -165,9 +172,11 @@
 stanza similar to the following to your ZCML configuration to setup a
 named store.
 
+.. code-block:: xml
+
   <store name="test" uri="sqlite:" />
 
-With that in place getUtility(IZStorm).get("test") will return the
+With that in place ``getUtility(IZStorm).get("test")`` will return the
 store named "test".
 
 
@@ -280,7 +289,7 @@
   ...         self.person = person
   ...         self.team = team
 
-  >>> class Team(Person):
+  >>> class Team(Storm):
   ...
   ...     __storm_table__ = "team"
   ...
@@ -324,8 +333,8 @@
 ResultSet interfaces
 --------------------
 
-Query results provide IResultSet (or ISQLObjectResultSet if SQLObject's
-compatibility layer is used).
+Query results provide ``IResultSet`` (or ``ISQLObjectResultSet`` if
+SQLObject's compatibility layer is used).
 
   >>> from storm.zope.interfaces import IResultSet, ISQLObjectResultSet
   >>> from storm.store import EmptyResultSet, ResultSet
@@ -339,13 +348,9 @@
   True
 
 
-The End
--------
-
+..
   >>> Team._storm_property_registry.clear()
   >>> TeamMembership._storm_property_registry.clear()
   >>> Person._storm_property_registry.clear()
   >>> transaction.abort()
   >>> zstorm._reset()
-
-# vim:ts=4:sw=4:et

=== modified file 'storm/tests/__init__.py'
--- storm/tests/__init__.py	2019-08-11 17:51:37 +0000
+++ storm/tests/__init__.py	2020-05-26 10:31:46 +0000
@@ -29,6 +29,7 @@
     ]
 
 import doctest
+from itertools import chain
 import os
 import unittest
 
@@ -71,14 +72,16 @@
     topdir = os.path.abspath(
         os.path.join(os.path.dirname(__file__), os.pardir, os.pardir))
     testdir = os.path.dirname(__file__)
+    docdir = os.path.join(os.path.dirname(testdir), "docs")
     testpaths = set(testpaths)
-    for root, dirnames, filenames in os.walk(testdir):
+    for root, dirnames, filenames in chain(os.walk(testdir), os.walk(docdir)):
         for filename in filenames:
             filepath = os.path.join(root, filename)
             relpath = filepath[len(topdir)+1:]
 
             if (filename == "__init__.py" or filename.endswith(".pyc") or
-                relpath == os.path.join("storm", "tests", "conftest.py")):
+                    relpath == os.path.join("storm", "docs", "conf.py") or
+                    relpath == os.path.join("storm", "tests", "conftest.py")):
                 # Skip non-tests.
                 continue
 
@@ -95,10 +98,9 @@
                 module = __import__(modpath, None, None, [""])
                 suite.addTest(
                     unittest.defaultTestLoader.loadTestsFromModule(module))
-            elif filename.endswith(".txt"):
+            elif filename.endswith(".rst"):
                 load_test = True
-                if relpath == os.path.join(
-                        "storm", "tests", "zope", "README.txt"):
+                if relpath == os.path.join("storm", "docs", "zope.rst"):
                     # Special case the inclusion of the Zope-dependent
                     # ZStorm doctest.
                     import storm.tests.zope as ztest

=== modified file 'tox.ini'
--- tox.ini	2019-11-21 01:57:01 +0000
+++ tox.ini	2020-05-26 10:31:46 +0000
@@ -5,6 +5,7 @@
     py36-{cextensions,nocextensions}
     py37-{cextensions,nocextensions}
     py38-{cextensions,nocextensions}
+    docs
 
 [testenv]
 deps =
@@ -15,3 +16,11 @@
     nocextensions: STORM_CEXTENSIONS = 0
 commands =
     python dev/test {posargs}
+
+[testenv:docs]
+basepython =
+    python3
+commands =
+    sphinx-build -b html -d storm/docs/_build/doctrees storm/docs storm/docs/_build/html
+deps =
+    .[doc]