Let intersphinx links to Minimum/Maximum work by putting them in the …

…docs. Also expose AbstractValue from zope.minmax; it was already documented as such.

CHANGES.rst

@@ -5,7 +5,8 @@
 2.2.1 (unreleased)
 ==================
 
-- Nothing changed yet.
+- Make the ``AbstractValue`` class public in ``zope.minmax``. It was
+  already documented to be public.
 
 
 2.2.0 (2017-08-14)

docs/conf.py

@@ -15,6 +15,9 @@
 
 import sys
 import os
+import pkg_resources
+sys.path.append(os.path.abspath('../src'))
+rqmt = pkg_resources.require('zope.minmax')[0]
 
 # 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
@@ -58,9 +61,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.1'
+version = '%s.%s' % tuple(map(int, rqmt.version.split('.')[:2]))
 # The full version, including alpha/beta/rc tags.
-release = '2.1'
+release = rqmt.version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -78,7 +81,7 @@
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-#default_role = None
+default_role = 'obj'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
@@ -266,4 +269,11 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {
+    'http://docs.python.org/': None,
+    'https://persistent.readthedocs.io/en/latest/': None,
+}
+
+autodoc_default_flags = ['members', 'show-inheritance']
+autoclass_content = 'both'
+autodoc_member_order = 'bysource'

docs/index.rst

@@ -1,21 +1,21 @@
-:mod:`zope.minmax`
-==================
+=================
+ ``zope.minmax``
+=================
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
    narrative
-   api
    hacking
 
 
 
-Indices and tables
-==================
+====================
+ Indices and tables
+====================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/narrative.rst

@@ -1,15 +1,23 @@
-Conflict Resolution using Maximum or Minimum Values
-===================================================
+=====================================================
+ Conflict Resolution using Maximum or Minimum Values
+=====================================================
 
 The :class:`zope.minmax.AbstractValue` class provides a super class which can
 be subclassed to store arbitrary *homogeneous* values in a persistent
 storage and apply different conflict resolution policies.
 
+.. autoclass:: zope.minmax.interfaces.IAbstractValue
+.. autoclass:: zope.minmax.AbstractValue
+   :private-members:
+
 The subclasses defined here are resolving the conflicts using always
 either the maximum or the minimum of the conflicting values.
 
 Maximum
--------
+=======
+
+.. autoclass:: zope.minmax.Maximum
+
 
 The :class:`zope.minmax.Maximum` class always resolves conflicts favoring the
 maximum value.  Let's instantiate one object and verify that it
@@ -59,7 +67,9 @@ Do notice that using a direct assignment to the value attribute is a
 more natural use.
 
 Minimum
--------
+=======
+
+.. autoclass:: zope.minmax.Minimum
 
 The :class:`zope.minmax.Minimum` class always resolves conflicts favoring the
 minimum value.  Again, we instantiate an object and verify that it
@@ -107,7 +117,7 @@ Please, notice, again, that using a direct assignment to the value
 attribute is a more natural use.
 
 Conflict Resolution
--------------------
+===================
 
 Now, we need to exercise the conflict resolution interface.
 First for the :class:`zope.minmax.Maximum`:

src/zope/minmax/__init__.py

@@ -1 +1 @@
-from zope.minmax._minmax import Maximum, Minimum
+from zope.minmax._minmax import Maximum, Minimum, AbstractValue

src/zope/minmax/_minmax.py

@@ -5,6 +5,11 @@
 
 @zope.interface.implementer(interfaces.IAbstractValue)
 class AbstractValue(persistent.Persistent):
+    """
+    Abstract implementation of `zope.minmax.interfaces.IAbstractValue`.
+
+    Subclasses *must* implement `_p_resolveConflict`.
+    """
 
     def __init__(self, value=None):
         self.value = value
@@ -22,6 +27,11 @@ def __bool__(self):
     __nonzero__ = __bool__
 
     def _p_resolveConflict(self, old, commited, new):
+        """
+        Subclasses must implement this method.
+
+        :raises NotImplementedError: Unless subclasses override.
+        """
         raise NotImplementedError()
 
 class Maximum(AbstractValue):