API documentation.intersphinx

This will allow for intersphinx links to work from other projects.

This may need to have the RTD box "install project in virtual env"
checked if it isn't already.

The version number in the docs is out of sync, I'll address that in a follow-up PR.

5 files changed, 273 insertions, 47 deletions

diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 0000000..88b9c53
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,207 @@
+=====
+ API
+=====
+
+This document describes the low-level API of the interfaces and
+classes provided by this package. The narrative documentation is a
+better guide to the intended usage.
+
+Interfaces
+==========
+
+.. autoclass:: zope.schema.interfaces.IField
+.. autoclass:: zope.schema.interfaces.IFromUnicode
+.. autoclass:: zope.schema.interfaces.IChoice
+.. autoclass:: zope.schema.interfaces.IContextAwareDefaultFactory
+.. autoclass:: zope.schema.interfaces.IOrderable
+.. autoclass:: zope.schema.interfaces.ILen
+.. autoclass:: zope.schema.interfaces.IMinMax
+.. autoclass:: zope.schema.interfaces.IMinMaxLen
+.. autoclass:: zope.schema.interfaces.IInterfaceField
+.. autoclass:: zope.schema.interfaces.IBool
+.. autoclass:: zope.schema.interfaces.IObject
+.. autoclass:: zope.schema.interfaces.IDict
+
+Strings
+-------
+
+.. autoclass:: zope.schema.interfaces.IBytes
+.. autoclass:: zope.schema.interfaces.IBytesLine
+.. autoclass:: zope.schema.interfaces.IText
+.. autoclass:: zope.schema.interfaces.ITextLine
+.. autoclass:: zope.schema.interfaces.IASCII
+.. autoclass:: zope.schema.interfaces.IASCIILine
+
+.. autoclass:: zope.schema.interfaces.IPassword
+.. autoclass:: zope.schema.interfaces.IURI
+.. autoclass:: zope.schema.interfaces.IId
+.. autoclass:: zope.schema.interfaces.IDottedName
+
+
+Numbers
+-------
+
+.. autoclass:: zope.schema.interfaces.IInt
+.. autoclass:: zope.schema.interfaces.IFloat
+.. autoclass:: zope.schema.interfaces.IDecimal
+
+Date/Time
+---------
+
+.. autoclass:: zope.schema.interfaces.IDatetime
+.. autoclass:: zope.schema.interfaces.IDate
+.. autoclass:: zope.schema.interfaces.ITimedelta
+.. autoclass:: zope.schema.interfaces.ITime
+
+
+Collections
+-----------
+.. autoclass:: zope.schema.interfaces.IIterable
+.. autoclass:: zope.schema.interfaces.IContainer
+.. autoclass:: zope.schema.interfaces.ICollection
+.. autoclass:: zope.schema.interfaces.ISequence
+.. autoclass:: zope.schema.interfaces.IUnorderedCollection
+.. autoclass:: zope.schema.interfaces.IAbstractSet
+.. autoclass:: zope.schema.interfaces.IAbstractBag
+
+.. autoclass:: zope.schema.interfaces.ITuple
+.. autoclass:: zope.schema.interfaces.IList
+.. autoclass:: zope.schema.interfaces.ISet
+.. autoclass:: zope.schema.interfaces.IFrozenSet
+
+Events
+------
+
+.. autoclass:: zope.schema.interfaces.IBeforeObjectAssignedEvent
+.. autoclass:: zope.schema.interfaces.IFieldEvent
+.. autoclass:: zope.schema.interfaces.IFieldUpdatedEvent
+
+Vocabularies
+------------
+
+.. autoclass:: zope.schema.interfaces.ITerm
+.. autoclass:: zope.schema.interfaces.ITokenizedTerm
+.. autoclass:: zope.schema.interfaces.ITitledTokenizedTerm
+.. autoclass:: zope.schema.interfaces.ISource
+.. autoclass:: zope.schema.interfaces.ISourceQueriables
+.. autoclass:: zope.schema.interfaces.IContextSourceBinder
+.. autoclass:: zope.schema.interfaces.IBaseVocabulary
+.. autoclass:: zope.schema.interfaces.IIterableVocabulary
+.. autoclass:: zope.schema.interfaces.IIterableSource
+.. autoclass:: zope.schema.interfaces.IVocabulary
+.. autoclass:: zope.schema.interfaces.IVocabularyTokenized
+.. autoclass:: zope.schema.interfaces.ITreeVocabulary
+.. autoclass:: zope.schema.interfaces.IVocabularyRegistry
+.. autoclass:: zope.schema.interfaces.IVocabularyFactory
+
+Exceptions
+----------
+
+.. autoexception:: zope.schema._bootstrapinterfaces.ValidationError
+
+.. exception:: zope.schema.ValidationError
+
+   The preferred alias for :class:`zope.schema._bootstrapinterfaces.ValidationError`.
+
+.. autoexception:: zope.schema.interfaces.StopValidation
+.. autoexception:: zope.schema.interfaces.RequiredMissing
+.. autoexception:: zope.schema.interfaces.WrongType
+.. autoexception:: zope.schema.interfaces.ConstraintNotSatisfied
+.. autoexception:: zope.schema.interfaces.NotAContainer
+.. autoexception:: zope.schema.interfaces.NotAnIterator
+
+.. autoexception:: zope.schema.interfaces.TooSmall
+.. autoexception:: zope.schema.interfaces.TooBig
+.. autoexception:: zope.schema.interfaces.TooLong
+.. autoexception:: zope.schema.interfaces.TooShort
+.. autoexception:: zope.schema.interfaces.InvalidValue
+.. autoexception:: zope.schema.interfaces.WrongContainedType
+.. autoexception:: zope.schema.interfaces.NotUnique
+.. autoexception:: zope.schema.interfaces.SchemaNotFullyImplemented
+.. autoexception:: zope.schema.interfaces.SchemaNotProvided
+.. autoexception:: zope.schema.interfaces.InvalidURI
+.. autoexception:: zope.schema.interfaces.InvalidId
+.. autoexception:: zope.schema.interfaces.InvalidDottedName
+.. autoexception:: zope.schema.interfaces.Unbound
+
+Schema APIs
+===========
+
+.. autofunction:: zope.schema.getFields
+.. autofunction:: zope.schema.getFieldsInOrder
+.. autofunction:: zope.schema.getFieldNames
+.. autofunction:: zope.schema.getFieldNamesInOrder
+.. autofunction:: zope.schema.getValidationErrors
+.. autofunction:: zope.schema.getSchemaValidationErrors
+
+Fields
+======
+
+.. autoclass:: zope.schema.Field
+.. autoclass:: zope.schema._field.AbstractCollection
+.. autoclass:: zope.schema.ASCII
+   :no-show-inheritance:
+.. autoclass:: zope.schema.ASCIILine
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Bool
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Bytes
+   :no-show-inheritance:
+.. autoclass:: zope.schema.BytesLine
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Choice
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Container
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Date
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Datetime
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Decimal
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Dict
+   :no-show-inheritance:
+.. autoclass:: zope.schema.DottedName
+   :no-show-inheritance:
+
+.. autoclass:: zope.schema.Float
+   :no-show-inheritance:
+.. autoclass:: zope.schema.FrozenSet
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Id
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Int
+   :no-show-inheritance:
+.. autoclass:: zope.schema.InterfaceField
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Iterable
+   :no-show-inheritance:
+.. autoclass:: zope.schema.List
+.. autoclass:: zope.schema.MinMaxLen
+.. autoclass:: zope.schema.NativeString
+.. autoclass:: zope.schema.NativeStringLine
+.. autoclass:: zope.schema.Object
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Orderable
+.. autoclass:: zope.schema.Password
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Set
+.. autoclass:: zope.schema.SourceText
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Text
+   :no-show-inheritance:
+.. autoclass:: zope.schema.TextLine
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Time
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Timedelta
+   :no-show-inheritance:
+.. autoclass:: zope.schema.Tuple
+.. autoclass:: zope.schema.URI
+   :no-show-inheritance:
+
+Accessors
+=========
+
+.. automodule:: zope.schema.accessors
+.. autofunction:: zope.schema.accessors.accessors
diff --git a/docs/conf.py b/docs/conf.py
index 7cf97e7..92020aa 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,7 +25,13 @@ import sys, os
 
 # 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.viewcode']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
+    'repoze.sphinx.autointerface',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -240,3 +246,16 @@ texinfo_documents = [
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+intersphinx_mapping = {
+    'https://docs.python.org/': None,
+}
+
+extlinks = {'issue': ('https://github.com/zopefoundation/zope.schema/issues/%s',
+                      'issue #'),
+            'pr': ('https://github.com/zopefoundation/zope.schema/pull/%s',
+                   'pull request #')}
+
+autodoc_default_flags = ['members', 'show-inheritance']
+autoclass_content = 'both'
+autodoc_member_order = 'bysource'
diff --git a/docs/fields.rst b/docs/fields.rst
index 1a9981b..2048b2d 100644
--- a/docs/fields.rst
+++ b/docs/fields.rst
@@ -21,7 +21,7 @@ Scalar fields represent simple. immutable Python types.
 Bytes
 #####
 
-:class:`zope.schema._field.Bytes` fields contain binary data, represented
+:class:`zope.schema.Bytes` fields contain binary data, represented
 as a sequence of bytes (``str`` in Python2, ``bytes`` in Python3).
 
 Conversion from Unicode:
@@ -30,7 +30,7 @@ Conversion from Unicode:
 
    >>> from zope.schema._compat import b
    >>> from zope.schema._compat import u
-   >>> from zope.schema._field import Bytes
+   >>> from zope.schema import Bytes
    >>> obj = Bytes(constraint=lambda v: b('x') in v)
    >>> obj.fromUnicode(u(" foo x.y.z bat"))
    ' foo x.y.z bat'
@@ -42,14 +42,14 @@ Conversion from Unicode:
 ASCII
 #####
 
-:class:`zope.schema._field.ASCII` fields are a restricted form of
-:class:`zope.schema._field.Bytes`:  they can contain only 7-bit bytes.
+:class:`zope.schema.ASCII` fields are a restricted form of
+:class:`zope.schema.Bytes`:  they can contain only 7-bit bytes.
 
 Validation accepts empty strings:
 
 .. doctest::
 
-   >>> from zope.schema._field import ASCII
+   >>> from zope.schema import ASCII
    >>> ascii = ASCII()
    >>> empty = ''
    >>> ascii._validate(empty)
@@ -74,26 +74,26 @@ but fails with 8-bit (encoded) strings:
 BytesLine
 #########
 
-:class:`zope.schema._field.BytesLine` fields are a restricted form of
-:class:`zope.schema._field.Bytes`:  they cannot contain newlines.
+:class:`zope.schema.BytesLine` fields are a restricted form of
+:class:`zope.schema.Bytes`:  they cannot contain newlines.
 
 ASCIILine
 #########
 
-:class:`zope.schema._field.BytesLine` fields are a restricted form of
-:class:`zope.schema._field.ASCII`:  they cannot contain newlines.
+:class:`zope.schema.BytesLine` fields are a restricted form of
+:class:`zope.schema.ASCII`:  they cannot contain newlines.
 
 Float
 #####
 
-:class:`zope.schema._field.Float` fields contain binary data, represented
+:class:`zope.schema.Float` fields contain binary data, represented
 as a a Python ``float``.
 
 Conversion from Unicode:
 
 .. doctest::
 
-   >>> from zope.schema._field import Float
+   >>> from zope.schema import Float
    >>> f = Float()
    >>> f.fromUnicode("1.25")
    1.25
@@ -105,14 +105,14 @@ Conversion from Unicode:
 Decimal
 #######
 
-:class:`zope.schema._field.Decimal` fields contain binary data, represented
-as a a Python ``decimal.Decimal``.
+:class:`zope.schema.Decimal` fields contain binary data, represented
+as a a Python :class:`decimal.Decimal`.
 
 Conversion from Unicode:
 
 .. doctest::
 
-   >>> from zope.schema._field import Decimal
+   >>> from zope.schema import Decimal
    >>> f = Decimal()
    >>> import decimal
    >>> isinstance(f.fromUnicode("1.25"), decimal.Decimal)
@@ -127,31 +127,31 @@ Conversion from Unicode:
 DateTime
 ########
 
-:class:`zope.schema._field.DateTime` fields contain binary data, represented
-as a a Python ``datetime.DateTime``.
+:class:`zope.schema.DateTime` fields contain binary data, represented
+as a a Python :class:`datetime.datetime`.
 
 Date
 ####
 
-:class:`zope.schema._field.Date` fields contain binary data, represented
-as a a Python ``datetime.Date``.
+:class:`zope.schema.Date` fields contain binary data, represented
+as a a Python :class:`datetime.date`.
 
 TimeDelta
 #########
 
-:class:`zope.schema._field.TimeDelta` fields contain binary data, represented
-as a a Python ``datetime.TimeDelta``.
+:class:`zope.schema.TimeDelta` fields contain binary data, represented
+as a a Python :class:`datetime.timedelta`.
 
 Time
 ####
 
-:class:`zope.schema._field.Time` fields contain binary data, represented
-as a a Python ``datetime.Time``.
+:class:`zope.schema.Time` fields contain binary data, represented
+as a a Python :class:`datetime.time`.
 
 Choice
 ######
 
-:class:`zope.schema._field.Choice` fields are constrained to values drawn
+:class:`zope.schema.Choice` fields are constrained to values drawn
 from a specified set, which can be static or dynamic.
 
 Conversion from Unicode enforces the constraint:
@@ -160,7 +160,7 @@ Conversion from Unicode enforces the constraint:
 
    >>> from zope.schema.interfaces import IFromUnicode
    >>> from zope.schema.vocabulary import SimpleVocabulary
-   >>> from zope.schema._field import Choice
+   >>> from zope.schema import Choice
    >>> t = Choice(
    ...     vocabulary=SimpleVocabulary.fromValues([u('foo'),u('bar')]))
    >>> IFromUnicode.providedBy(t)
@@ -173,8 +173,8 @@ Conversion from Unicode enforces the constraint:
    u'foo'
 
 By default, ValueErrors are thrown if duplicate values or tokens
-are passed in. If you are using this vocabulary as part of a form 
-that is generated from non-pristine data, this may not be the 
+are passed in. If you are using this vocabulary as part of a form
+that is generated from non-pristine data, this may not be the
 desired behavior. If you want to swallow these exceptions, pass
 in swallow_duplicates=True when initializing the vocabulary. See
 the test cases for an example.
@@ -182,14 +182,14 @@ the test cases for an example.
 URI
 ###
 
-:class:`zope.schema._field.URI` fields contain native Python strings
+:class:`zope.schema.URI` fields contain native Python strings
 (``str``), matching the "scheme:data" pattern.
 
 Validation ensures that the pattern is matched:
 
 .. doctest::
 
-   >>> from zope.schema._field import URI
+   >>> from zope.schema import URI
    >>> uri = URI(__name__='test')
    >>> uri.validate(b("http://www.python.org/foo/bar"))
    >>> uri.validate(b("DAV:"))
@@ -217,14 +217,14 @@ Conversion from Unicode:
 DottedName
 ##########
 
-:class:`zope.schema._field.DottedName` fields contain native Python strings
+:class:`zope.schema.DottedName` fields contain native Python strings
 (``str``), containing zero or more "dots" separating elements of the
 name.  The minimum and maximum number of dots can be passed to the
 constructor:
 
 .. doctest::
 
-   >>> from zope.schema._field import DottedName
+   >>> from zope.schema import DottedName
    >>> DottedName(min_dots=-1)
    Traceback (most recent call last):
    ...
@@ -306,14 +306,14 @@ Validation ensures that the pattern is matched:
 Id
 ##
 
-:class:`zope.schema._field.Id` fields contain native Python strings
+:class:`zope.schema.Id` fields contain native Python strings
 (``str``), matching either the URI pattern or a "dotted name".
 
 Validation ensures that the pattern is matched:
 
 .. doctest::
 
-   >>> from zope.schema._field import Id
+   >>> from zope.schema import Id
    >>> id = Id(__name__='test')
    >>> id.validate("http://www.python.org/foo/bar")
    >>> id.validate("zope.app.content")
@@ -396,8 +396,8 @@ Creating a custom collection field
 Ideally, custom collection fields have interfaces that inherit appropriately
 from either zope.schema.interfaces.ISequence or
 zope.schema.interfaces.IUnorderedCollection.  Most collection fields should be
-able to subclass zope.schema._field.AbstractCollection to get the necessary
-behavior.  Notice the behavior of the Set field in zope.schema._field: this
+able to subclass :class:`zope.schema._field.AbstractCollection` to get the necessary
+behavior.  Notice the behavior of the Set field in zope.schema: this
 would also be necessary to implement a Bag.
 
 Choices and Vocabularies
@@ -405,7 +405,7 @@ Choices and Vocabularies
 
 Choice fields are the schema way of spelling enumerated fields and more.  By
 providing a dynamically generated vocabulary, the choices available to a
-choice field can be contextually calculated.  
+choice field can be contextually calculated.
 
 Simple choices do not have to explicitly use vocabularies:
 
@@ -428,7 +428,7 @@ have a simple interface, as defined in
 zope.schema.interfaces.IBaseVocabulary.  A vocabulary must minimally be able
 to determine whether it contains a value, to create a term object for a value,
 and to return a query interface (or None) to find items in itself.  Term
-objects are an abstraction that wraps a vocabulary value.  
+objects are an abstraction that wraps a vocabulary value.
 
 The Zope application server typically needs a fuller interface that provides
 "tokens" on its terms: ASCII values that have a one-to-one relationship to the
@@ -450,13 +450,13 @@ registered vocabularies can simply be functions that rely on SimpleVocabulary:
    >>> def myDynamicVocabulary(context):
    ...     v = dynamic_context_calculation_that_returns_an_iterable(context)
    ...     return SimpleVocabulary.fromValues(v)
-   ... 
+   ...
 
 The vocabulary interface is simple enough that writing a custom vocabulary is
 not too difficult itself.
 
 See zope.schema.vocabulary.TreeVocabulary for another
-IBaseVocabulary supporting vocabulary that provides a nested, tree-like 
+IBaseVocabulary supporting vocabulary that provides a nested, tree-like
 structure.
 
 Choices and Collections
@@ -476,7 +476,7 @@ While fields support several use cases, including code documentation and data
 description and even casting, a significant use case influencing their design is
 to support form generation -- generating widgets for a field.  Choice and
 collection fields are expected to be used within widget frameworks.  The
-zope.app approach typically (but configurably) uses multiple dispatches to 
+zope.app approach typically (but configurably) uses multiple dispatches to
 find widgets on the basis of various aspects of the fields.
 
 Widgets for all fields are found by looking up a browser view of the field
@@ -498,5 +498,4 @@ value_type field, and the vocabulary.  Further lookups may even be configured
 on the basis of uniqueness and other constraints.
 
 This level of indirection may be unnecessary for some applications, and can be
-disabled with simple ZCML changes within `zope.app`.
-
+disabled with simple ZCML changes within ``zope.app``.
diff --git a/docs/index.rst b/docs/index.rst
index c018c40..ed241af 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,6 +10,7 @@ Contents:
    fields
    sources
    validation
+   api
    hacking
 
 Indices and tables
diff --git a/docs/validation.rst b/docs/validation.rst
index c823cce..a932283 100644
--- a/docs/validation.rst
+++ b/docs/validation.rst
@@ -4,10 +4,10 @@ Schema Validation
 
 There are two helper methods to verify schemas and interfaces:
 
-getValidationErrors
+:func:`~.getValidationErrors`
     first validates via the zope.schema field validators. If that succeeds the
     invariants are checked.
-getSchemaValidationErrors
+:func:`~.getSchemaValidationErrors`
     *only* validates via the zope.schema field validators. The invariants are
     *not* checked.
 
@@ -28,7 +28,7 @@ Create an interface to validate against:
    ...         _a_greater_b_called.append(obj)
    ...         if obj.a <= obj.b:
    ...             raise zope.interface.Invalid("%s<=%s" % (obj.a, obj.b))
-   ...     
+   ...
 
 Create a silly model:
 
@@ -79,7 +79,7 @@ The `getSchemaValidationErrors` function returns the same result:
    'SchemaNotFullyImplemented'
    >>> r[1][1].args[0].args
    ("'TwoInts' object has no attribute 'b'",)
- 
+
 Note that see no error from the invariant because the invariants are not
 validated if there are other schema errors.
 
@@ -185,7 +185,7 @@ but not with an error with different arguments:
    >>> v1 == v3
    False
 
-We can also compare validation errors with other things then errors. This 
+We can also compare validation errors with other things then errors. This
 was running into an AttributeError in previous versions of zope.schema. e.g.
 AttributeError: 'NoneType' object has no attribute 'args'