Merge pull request #130 from azmeuk/doclinks

Added internal documentation links

BTrees/Interfaces.py

@@ -33,7 +33,7 @@ class IReadSequence(Interface):
     def __getitem__(index):
         """Return the value at the given index.
 
-        An IndexError is raised if the index cannot be found.
+        An :class:`IndexError` is raised if the index cannot be found.
         """
 
     def __getslice__(index1, index2):
@@ -52,9 +52,9 @@ def has_key(key):
         """
 
     def keys(min=None, max=None, excludemin=False, excludemax=False):
-        """Return an IReadSequence containing the keys in the collection.
+        """Return an :class:`~BTrees.Interfaces.IReadSequence` containing the keys in the collection.
 
-        The type of the IReadSequence is not specified.  It could be a list
+        The type of the :class:`~BTrees.Interfaces.IReadSequence` is not specified.  It could be a list
         or a tuple or some other type.
 
         All arguments are optional, and may be specified as keyword
@@ -63,7 +63,7 @@ def keys(min=None, max=None, excludemin=False, excludemax=False):
         If a min is specified, then output is constrained to keys greater
         than or equal to the given min, and, if excludemin is specified and
         true, is further constrained to keys strictly greater than min.  A
-        min value of None is ignored.  If min is None or not specified, and
+        min value of None is ignored. If min is None or not specified, and
         excludemin is true, the smallest key is excluded.
 
         If a max is specified, then output is constrained to keys less than
@@ -101,7 +101,7 @@ def insert(key):
     def remove(key):
         """Remove the key from the set.
 
-        Raises KeyError if key is not in the set.
+        Raises :class:`KeyError` if key is not in the set.
         """
 
     def update(seq):
@@ -137,13 +137,15 @@ class IMinimalDictionary(ISized, IKeyed):
     def get(key, default):
         """Get the value associated with the given key.
 
-        Return the default if has_key(key) is false.
+        Return the default if :meth:`~BTrees.Interfaces.IKeyed.has_key` is false
+        with the given key.
         """
 
     def __getitem__(key):
         """Get the value associated with the given key.
 
-        Raise KeyError if has_key(key) is false.
+        Raise :class:`KeyError` if :meth:`~BTrees.Interfaces.IKeyed.has_key` is false
+        with the given key.
         """
 
     def __setitem__(key, value):
@@ -152,13 +154,14 @@ def __setitem__(key, value):
     def __delitem__(key):
         """Delete the value associated with the given key.
 
-        Raise KeyError if has_key(key) is false.
+        Raise class:`KeyError` if :meth:`~BTrees.Interfaces.IKeyed.has_key` is false
+        with the given key.
         """
 
     def values(min=None, max=None, excludemin=False, excludemax=False):
-        """Return an IReadSequence containing the values in the collection.
+        """Return an :class:`BTrees.Interfaces.IReadSequence` containing the values in the collection.
 
-        The type of the IReadSequence is not specified.  It could be a list
+        The type of the :class:`~BTrees.Interfaces.IReadSequence` is not specified. It could be a list
         or a tuple or some other type.
 
         All arguments are optional, and may be specified as keyword
@@ -180,11 +183,11 @@ def values(min=None, max=None, excludemin=False, excludemax=False):
         """
 
     def items(min=None, max=None, excludemin=False, excludemax=False):
-        """Return an IReadSequence containing the items in the collection.
+        """Return an :class:`BTrees.Interfaces.IReadSequence` containing the items in the collection.
 
         An item is a 2-tuple, a (key, value) pair.
 
-        The type of the IReadSequence is not specified.  It could be a list
+        The type of the :class:`BTrees.Interfaces.IReadSequence` is not specified.  It could be a list
         or a tuple or some other type.
 
         All arguments are optional, and may be specified as keyword
@@ -226,19 +229,19 @@ def byValue(minValue):
     def setdefault(key, d):
         """D.setdefault(k, d) -> D.get(k, d), also set D[k]=d if k not in D.
 
-        Return the value like get() except that if key is missing, d is both
+        Return the value like :meth:`~BTrees.Interfaces.IMinimalDictionary.get` except that if key is missing, d is both
         returned and inserted into the dictionary as the value of k.
 
-        Note that, unlike as for Python's dict.setdefault(), d is not
+        Note that, unlike as for Python's :meth:`dict.setdefault`, d is not
         optional.  Python defaults d to None, but that doesn't make sense
         for mappings that can't have None as a value (for example, an
-        IIBTree can have only integers as values).
+        :class:`~BTrees.IIBTree.IIBTree` can have only integers as values).
         """
 
     def pop(key, d):
         """D.pop(k[, d]) -> v, remove key and return the corresponding value.
 
-        If key is not found, d is returned if given, otherwise KeyError is
+        If key is not found, d is returned if given, otherwise :class:`KeyError` is
         raised.
         """
 
@@ -271,11 +274,11 @@ class IMerge(Interface):
     These methods are supplied in modules that define collection
     classes with particular key and value types. The operations apply
     only to collections from the same module.  For example, the
-    IIBTree.union can only be used with IIBTree.IIBTree,
-    IIBTree.IIBucket, IIBTree.IISet, and IIBTree.IITreeSet.
+    :meth:`BTrees.IIBTree.IIBTree.union` can only be used with :class:`~BTrees.IIBTree.IIBTree`,
+    :class:`~BTrees.IIBTree.IIBucket`, :class:`~BTrees.IIBTree.IISet`, and :class:`~BTrees.IIBTree.IITreeSet`.
 
-    The implementing module has a value type. The IOBTree and OOBTree
-    modules have object value type. The IIBTree and OIBTree modules
+    The implementing module has a value type. The :class:`~BTrees.IOBTree.IOBTree` and :class:`~BTrees.OOBTree.OOBTree`
+    modules have object value type. The :class:`~BTrees.IIBTree.IIBTree` and :class:`~BTrees.OIBTree.OIBTree` modules
     have integer value types. Other modules may be defined in the
     future that have other value types.
 
@@ -418,9 +421,9 @@ def weightedIntersection(c1, c2, weight1=1, weight2=1):
 
 
 class IMergeIntegerKey(IMerge):
-    """IMerge-able objects with integer keys.
+    """:class:`~BTrees.Interfaces.IMerge`-able objects with integer keys.
 
-    Concretely, this means the types in IOBTree and IIBTree.
+    Concretely, this means the types in :class:`~BTree.IOBTree.IOBTree` and :class:`~BTrees.IIBTree.IIBTree`.
     """
 
     def multiunion(seq):
@@ -432,18 +435,18 @@ def multiunion(seq):
         + An integer, which is added to the union.
 
         + A Set or TreeSet from the same module (for example, an
-          IIBTree.TreeSet for IIBTree.multiunion()).  The elements of the
+          :class:`BTrees.IIBTree.TreeSet` for :meth:`BTrees.IIBTree.multiunion`).  The elements of the
           set are added to the union.
 
         + A Bucket or BTree from the same module (for example, an
-          IOBTree.IOBTree for IOBTree.multiunion()).  The keys of the
+          :class:`BTrees.IOBTree.IOBTree` for :meth:`BTrees.IOBTree.multiunion`).  The keys of the
           mapping are added to the union.
 
         The union is returned as a Set from the same module (for example,
-        IIBTree.multiunion() returns an IIBTree.IISet).
+        :meth:`BTrees.IIBTree.multiunion` returns an :class:`BTrees.IIBTree.IISet`).
 
         The point to this method is that it can run much faster than
-        doing a sequence of two-input union() calls.  Under the covers,
+        doing a sequence of two-input :meth:`~BTrees.Interfaces.IMerge.union` calls.  Under the covers,
         all the integers in all the inputs are sorted via a single
         linear-time radix sort, then duplicates are removed in a second
         linear-time pass.
@@ -482,7 +485,7 @@ class IIntegerObjectBTreeModule(_IMergeBTreeModule):
 
 class IUnsignedObjectBTreeModule(_IMergeBTreeModule):
     """
-    As for `IIntegerObjectBTreeModule` with unsigned integers.
+    As for :class:`~BTrees.Interfaces.IIntegerObjectBTreeModule` with unsigned integers.
     """
 
 

BTrees/check.py

@@ -16,7 +16,7 @@
 level.
 
 The primary function is check(btree), which performs value-based consistency
-checks of a kind btree._check() does not perform.  See the function docstring
+checks of a kind ``BTree._Tree._check()`` does not perform.  See the function docstring
 for details.
 
 display(btree) displays the internal structure of a BTree (TreeSet, etc) to
@@ -442,17 +442,17 @@ def visit_bucket(self, obj, path, parent, is_mapping,
 def check(btree):
     """Check internal value-based invariants in a BTree or TreeSet.
 
-    The btree._check() method checks internal C-level pointer consistency.
-    The check() function here checks value-based invariants:  whether the
+    The ``BTrees._base._Tree._check`` method checks internal C-level pointer consistency.
+    The :func:`~BTrees.check.check` function here checks value-based invariants:  whether the
     keys in leaf bucket and internal nodes are in strictly increasing order,
     and whether they all lie in their expected range.  The latter is a subtle
     invariant that can't be checked locally -- it requires propagating
     range info down from the root of the tree, and modifying it at each
     level for each child.
 
-    Raises AssertionError if anything is wrong, with a string detail
+    Raises :class:`AssertionError` if anything is wrong, with a string detail
     explaining the problems.  The entire tree is checked before
-    AssertionError is raised, and the string detail may be large (depending
+    :class:`AssertionError` is raised, and the string detail may be large (depending
     on how much went wrong).
     """
 

docs/conf.py

@@ -276,5 +276,5 @@
 intersphinx_mapping = {
     "python": ('https://docs.python.org/3/', None),
     "persistent": ('https://persistent.readthedocs.io/en/latest/', None),
-    "ZODB": ("http://www.zodb.org/en/latest/", None),
+    "ZODB": ("https://zodb-docs.readthedocs.io/en/latest/", None),
 }

docs/overview.rst

@@ -180,11 +180,11 @@ exclusive of the range's endpoints.
 
 
 Each of the modules also defines some functions that operate on BTrees --
-:func:`~BTrees._base.difference`, :func:`~BTrees._base.union`, and :func:`~BTrees._base.intersection`.  The
-:func:`~BTrees._base.difference` function returns a Bucket, while the other two methods return
+:func:`~BTrees.Interfaces.IMerge.difference`, :func:`~BTrees.Interfaces.IMerge.union`, and :func:`~BTrees.Interfaces.IMerge.intersection`.  The
+:func:`~BTrees.Interfaces.IMerge.difference` function returns a Bucket, while the other two methods return
 a Set. If the keys are integers, then the module also defines
-:func:`~BTrees._base.multiunion`.  If the values are integers or floats, then the module also
-defines :func:`~BTrees._base.weightedIntersection` and :func:`~BTrees._base.weightedUnion`.  The function
+:func:`~BTrees.Interfaces.IMergeIntegerKey.multiunion`.  If the values are integers or floats, then the module also
+defines :func:`~BTrees.Interfaces.IIMerge.weightedIntersection` and :func:`~BTrees.Interfaces.IIMerge.weightedUnion`.  The function
 doc strings describe each function briefly.
 
 .. % XXX I'm not sure all of the following is actually correct.  The