Fix Sphinx warnings (issue #305)

Author: brunato

doc/api.rst

@@ -52,12 +52,13 @@ Schema level API
 .. class:: xmlschema.XMLSchema11
 
     The classes for XSD v1.0 and v1.1 schema instances. They are both generated by the
-    meta-class :class:`XMLSchemaMeta` and take the same API of :class:`XMLSchemaBase`.
+    meta-class :class:`XMLSchemaMeta` and take the same API of :class:`xmlschema.XMLSchemaBase`.
 
 .. autoclass:: xmlschema.XMLSchema
 
 .. autoclass:: xmlschema.XMLSchemaBase
 
+    .. autoattribute:: meta_schema
     .. autoattribute:: root
     .. automethod:: get_text
     .. autoattribute:: name
@@ -85,6 +86,7 @@ Schema level API
     .. automethod:: get_locations
     .. automethod:: include_schema
     .. automethod:: import_schema
+    .. automethod:: add_schema
     .. automethod:: export
     .. automethod:: resolve_qname
     .. automethod:: iter_globals
@@ -224,6 +226,18 @@ Translation API
 .. autofunction:: xmlschema.translation.deactivate
 
 
+.. _namespace-api:
+
+Namespaces API
+==============
+
+Classes for converting namespace representation or for accessing namespace objects:
+
+.. autoclass:: xmlschema.namespaces.NamespaceResourcesMap
+.. autoclass:: xmlschema.namespaces.NamespaceMapper
+.. autoclass:: xmlschema.namespaces.NamespaceView
+
+
 .. _xpath-api:
 
 XPath API

doc/conf.py

@@ -41,6 +41,21 @@
 # Option for autodoc: do not add module name as prefix to classes or functions.
 add_module_names = False
 
+nitpick_ignore = [
+    ('py:class', 'pathlib.Path'),
+    ('py:class', 'xml.etree.ElementTree.Element'),
+    ('py:class', 'xmlschema.aliases.T'),
+    ('py:class', 'xmlschema.namespaces.T'),
+    ('py:class', 'xmlschema.xpath.E'),
+    ('py:class', 'xmlschema.validators.xsdbase.DT'),
+    ('py:class', 'xmlschema.validators.xsdbase.ST'),
+    ('py:class', 'XsdValidator'),
+    ('py:class', 'XMLSchemaMeta'),
+    ('py:class', 'xmlschema.validators.schemas.XMLSchema10'),
+    ('py:meth', 'read'),
+    ('py:meth', 'write'),
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -65,14 +80,15 @@
 # The short X.Y version.
 version = '1.11'
 # The full version, including alpha/beta/rc tags.
-release = '1.11.2'
+release = '1.11.3'
 
 # 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
+# language = None
+language = 'en'  # required by Sphinx v5.0.0
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

doc/converters.rst

@@ -26,14 +26,14 @@ like JSON, because prefixed name is more manageable and readable than expanded f
 Available converters
 ====================
 
-The library includes some converters. The default converter :class:`XMLSchemaConverter`
+The library includes some converters. The default converter :class:`xmlschema.XMLSchemaConverter`
 is the base class of other converter types. Each derived converter type implements a
 well know convention, related to the conversion from XML to JSON data format:
 
-  * :class:`ParkerConverter`: `Parker convention <https://developer.mozilla.org/en-US/docs/Archive/JXON#The_Parker_Convention>`_
-  * :class:`BadgerFishConverter`: `BadgerFish convention <http://www.sklar.com/badgerfish/>`_
-  * :class:`AbderaConverter`: `Apache Abdera project convention <https://cwiki.apache.org/confluence/display/ABDERA/JSON+Serialization>`_
-  * :class:`JsonMLConverter`: `JsonML (JSON Mark-up Language) convention <http://www.jsonml.org/>`_
+  * :class:`xmlschema.ParkerConverter`: `Parker convention <https://developer.mozilla.org/en-US/docs/Archive/JXON#The_Parker_Convention>`_
+  * :class:`xmlschema.BadgerFishConverter`: `BadgerFish convention <http://www.sklar.com/badgerfish/>`_
+  * :class:`xmlschema.AbderaConverter`: `Apache Abdera project convention <https://cwiki.apache.org/confluence/display/ABDERA/JSON+Serialization>`_
+  * :class:`xmlschema.JsonMLConverter`: `JsonML (JSON Mark-up Language) convention <http://www.jsonml.org/>`_
 
 A summary of these and other conventions can be found on the wiki page
 `JSON and XML Conversion <http://wiki.open311.org/JSON_and_XML_Conversion/>`_.
@@ -46,18 +46,18 @@ base class options and attributes.
 
 Moreover there are also other two converters useful for specific cases:
 
-  * :class:`UnorderedConverter`: like default converter but with unordered decoding and encoding.
-  * :class:`ColumnarConverter`: a converter that remaps attributes as child elements in a
+  * :class:`xmlschema.UnorderedConverter`: like default converter but with unordered decoding and encoding.
+  * :class:`xmlschema.ColumnarConverter`: a converter that remaps attributes as child elements in a
     columnar shape (available since release v1.2.0).
-  * :class:`DataElementConverter`: a converter that converts XML to a tree of
-    :class:`DataElement` intances, Element-like objects with decoded values and
+  * :class:`xmlschema.DataElementConverter`: a converter that converts XML to a tree of
+    :class:`xmlschema.DataElement` instances, Element-like objects with decoded values and
     schema bindings (available since release v1.5.0).
 
 
 Create a custom converter
 =========================
 
-To create a new customized converter you have to subclass the :class:`XMLSchemaConverter`
+To create a new customized converter you have to subclass the :class:`xmlschema.XMLSchemaConverter`
 and redefine the two methods *element_decode* and *element_encode*. These methods are based
 on the namedtuple `ElementData`, an Element-like data structure that stores the decoded
 Element parts. This namedtuple is used by decoding and encoding methods as an intermediate

doc/extras.rst

@@ -27,10 +27,10 @@ Code generation with Jinja2 templates
 =====================================
 
 The module *xmlschema.extras.codegen* provides an abstract base class
-:class:`AbstractGenerator` for generate source code from parsed XSD
-schemas. The Jinja2 engine is embedded in that class and is empowered
-with a set of custom filters and tests for accessing to defined XSD
-schema components.
+:class:`xmlschema.extras.codegen.AbstractGenerator` for generate source
+code from parsed XSD schemas. The Jinja2 engine is embedded in that class
+and is empowered with a set of custom filters and tests for accessing to
+defined XSD schema components.
 
 
 Schema based filters
@@ -90,8 +90,8 @@ Type mapping
 ------------
 
 Each implementation of a generator class has an additional filter for translating
-types using the types map of the instance. For example a :class:`PythonGenerator`
-has the filter *python_type*.
+types using the types map of the instance.
+For example :class:`xmlschema.extras.codegen.PythonGenerator` has the filter *python_type*.
 
 These filters are based on a common method *map_type* that uses an instance
 dictionary built at initialization time from a class maps for builtin types
@@ -131,9 +131,9 @@ The module *xmlschema.extras.wsdl* provides a specialized schema-related
 XML document for WSDL 1.1.
 
 An example of
-specialization is the class :class:`Wsdl11Document`, usable for validating and
-parsing WSDL 1.1 documents, that can be imported from *wsdl* module of the *extra*
-subpackage:
+specialization is the class :class:`xmlschema.extras.wsdl.Wsdl11Document`, usable
+for validating and parsing WSDL 1.1 documents, that can be imported from *wsdl*
+module of the *extra* subpackage:
 
 .. doctest::
 

doc/features.rst

@@ -11,8 +11,8 @@ XSD 1.0 and 1.1 support
 =======================
 
 From release v1.0.14 XSD 1.1 support has been added to the library through the class
-:class:`XMLSchema11`. You have to use this class for XSD 1.1 schemas instead the default
-class :class:`XMLSchema`, that is linked to XSD 1.0 validator :class:`XMLSchema10`.
+:class:`xmlschema.XMLSchema11`. You have to use this class for XSD 1.1 schemas instead the default
+class :class:`xmlschema.XMLSchema`, that is linked to XSD 1.0 validator :class:`xmlschema.XMLSchema10`.
 
 The XSD 1.1 validator can be used also for validating XSD 1.0 schemas, except for a
 restricted set of cases related to content extension in a complexType (the extension
@@ -69,7 +69,7 @@ Lazy validation
 ===============
 
 From release v1.0.12 the document validation and the decoding API have an optional argument
-`lazy=False`, that can be changed to `True` for operating with a lazy :class:`XMLResource`.
+`lazy=False`, that can be changed to `True` for operating with a lazy :class:`xmlschema.XMLResource`.
 The lazy mode can be useful for validating and decoding big XML data files, consuming
 less memory.
 

doc/usage.rst

@@ -105,7 +105,7 @@ particurlaly useful when sources have no locations associated:
     ...            open('tests/test_cases/examples/vehicles/types.xsd')]
     >>> schema = xmlschema.XMLSchema(sources)
 
-or similarly to the previous example one can use the method :meth:`add_schema()`:
+or similarly to the previous example one can use the method :meth:`xmlschema.XMLSchemaBase.add_schema`:
 
 .. doctest::
 
@@ -129,7 +129,7 @@ Validation
 
 A schema instance has methods to validate an XML document against the schema.
 
-The first method is :meth:`XMLSchema.is_valid`, that returns ``True``
+The first method is :meth:`xmlschema.XMLSchemaBase.is_valid`, that returns ``True``
 if the XML argument is validated by the schema loaded in the instance,
 and returns ``False`` if the document is invalid.
 
@@ -145,8 +145,8 @@ and returns ``False`` if the document is invalid.
     False
 
 An alternative mode for validating an XML document is implemented by the method
-:meth:`XMLSchema.validate`, that raises an error when the XML doesn't conforms
-to the schema:
+:meth:`xmlschema.XMLSchemaBase.validate`, that raises an error when the XML doesn't
+conform to the schema:
 
 .. doctest::
 
@@ -497,9 +497,9 @@ See the :meth:`xmlschema.to_json` and :meth:`xmlschema.from_json` in the
 XML resources and documents
 ===========================
 
-Schemas and XML instances processing are based on the class :class:`XMLResource`,
+Schemas and XML instances processing are based on the class :class:`xmlschema.XMLResource`,
 that handles the loading and the iteration of XSD/XML data.
-Starting from v1.3.0 :class:`XMLResource` has been empowered with ElementTree-like
+Starting from v1.3.0 :class:`xmlschema.XMLResource` has been empowered with ElementTree-like
 XPath API. From the same release a new class :class:`xmlschema.XmlDocument` is
 available for representing XML resources with a related schema:
 

tox.ini

@@ -46,9 +46,10 @@ deps =
 
 [testenv:docs]
 commands =
-    make -C doc html
-    make -C doc latexpdf
-    make -C doc doctest
+    make -C doc html SPHINXOPTS="-W -n"
+    make -C doc latexpdf SPHINXOPTS="-W -n"
+    make -C doc doctest SPHINXOPTS="-W -n"
+    sphinx-build -W -n -T -b man doc build/sphinx/man
 
 [flake8]
 max-line-length = 100

xmlschema/converters/unordered.py

@@ -19,8 +19,8 @@
 
 class UnorderedConverter(XMLSchemaConverter):
     """
-    Same as :class:`XMLSchemaConverter` but :meth:`element_encode` returns
-    a dictionary for the content of the element, that can be used directly
+    Same as :class:`XMLSchemaConverter` but :meth:`XMLSchemaConverter.element_encode`
+    returns a dictionary for the content of the element, that can be used directly
     for unordered encoding mode. In this mode the order of the elements in
     the encoded output is based on the model visitor pattern rather than
     the order in which the elements were added to the input dictionary.

xmlschema/documents.py

@@ -251,7 +251,7 @@ def iter_decode(xml_document: Union[XMLSourceType, XMLResource],
     :param timeout: optional argument to pass for construct schema and \
     :class:`XMLResource` instances.
     :param lazy: optional argument for construct the :class:`XMLResource` instance.
-    :param kwargs: other optional arguments of :meth:`XMLSchema.iter_decode` \
+    :param kwargs: other optional arguments of :meth:`XMLSchemaBase.iter_decode` \
     as keyword arguments.
     :raises: :exc:`XMLSchemaValidationError` if the XML document is invalid and \
     ``validation='strict'`` is provided.
@@ -334,7 +334,7 @@ def to_json(xml_document: Union[XMLSourceType, XMLResource],
     :class:`XMLResource` instances.
     :param lazy: optional argument for construct the :class:`XMLResource` instance.
     :param json_options: a dictionary with options for the JSON serializer.
-    :param kwargs: optional arguments of :meth:`XMLSchema.iter_decode` as keyword arguments \
+    :param kwargs: optional arguments of :meth:`XMLSchemaBase.iter_decode` as keyword arguments \
     to variate the decoding process.
     :return: a string containing the JSON data if *fp* is `None`, otherwise doesn't \
     return anything. If ``validation='lax'`` keyword argument is provided the validation \
@@ -392,7 +392,7 @@ def from_json(source: Union[str, bytes, IO[str]],
     :param converter: an :class:`XMLSchemaConverter` subclass or instance to use \
     for the encoding.
     :param json_options: a dictionary with options for the JSON deserializer.
-    :param kwargs: other optional arguments of :meth:`XMLSchema.iter_encode` and \
+    :param kwargs: other optional arguments of :meth:`XMLSchemaBase.iter_encode` and \
     options for converter.
     :return: An element tree's Element instance. If ``validation='lax'`` keyword argument is \
     provided the validation errors are collected and returned coupled in a tuple with the \

xmlschema/extras/wsdl.py

@@ -464,7 +464,7 @@ class Wsdl11Document(XmlDocument):
     :param source: a string containing XML data or a file path or an URL or a \
     file like object or an ElementTree or an Element.
     :param cls: class to use for building the schema instance (for default \
-    :class:`XMLSchema10` is used).
+    :class:`xmlschema.XMLSchema10` is used).
     :param validation: the XSD validation mode to use for validating the XML document, \
     that can be 'strict' (default), 'lax' or 'skip'.
     :param maps: WSDL definitions shared maps.

xmlschema/validators/schemas.py

@@ -226,7 +226,7 @@ class XMLSchemaBase(XsdValidator, ElementPathMixin[Union[SchemaType, XsdElement]
     *chameleon* definitions.
     :ivar validation: validation mode, can be 'strict', 'lax' or 'skip'.
     :ivar maps: XSD global declarations/definitions maps. This is an instance of \
-    :class:`XsdGlobal`, that stores the *global_maps* argument or a new object \
+    :class:`XsdGlobals`, that stores the *global_maps* argument or a new object \
     when this argument is not provided.
     :ivar converter: the default converter used for XML data decoding/encoding.
     :ivar locations: schema location hints.
@@ -2009,7 +2009,7 @@ def decode(self, source: Union[XMLSourceType, XMLResource],
                validation: str = 'strict',
                *args: Any, **kwargs: Any) -> DecodeType[Any]:
         """
-        Decodes XML data. Takes the same arguments of the method :func:`XMLSchema.iter_decode`.
+        Decodes XML data. Takes the same arguments of the method :meth:`iter_decode`.
         """
         data, errors = [], []
         for result in self.iter_decode(source, path, schema_path, validation, *args, **kwargs):
@@ -2119,7 +2119,7 @@ def iter_encode(self, obj: Any, path: Optional[str] = None, validation: str = 'l
     def encode(self, obj: Any, path: Optional[str] = None, validation: str = 'strict',
                *args: Any, **kwargs: Any) -> EncodeType[Any]:
         """
-        Encodes to XML data. Takes the same arguments of the method :func:`XMLSchema.iter_encode`.
+        Encodes to XML data. Takes the same arguments of the method :meth:`iter_encode`.
 
         :return: An ElementTree's Element or a list containing a sequence of ElementTree's \
         elements if the argument *path* matches multiple XML data chunks. If *validation* \

xmlschema/validators/xsdbase.py

@@ -896,8 +896,8 @@ def validate(self, obj: ST,
         validations on XML data. The provided function is called for each traversed \
         element, with the XML element as 1st argument and the corresponding XSD \
         element as 2nd argument. It can be also a generator function and has to \
-        raise/yield :exc:`XMLSchemaValidationError` exceptions.
-        :raises: :exc:`XMLSchemaValidationError` if the XML data instance is invalid.
+        raise/yield :exc:`xmlschema.XMLSchemaValidationError` exceptions.
+        :raises: :exc:`xmlschema.XMLSchemaValidationError` if the XML data instance is invalid.
         """
         for error in self.iter_errors(obj, use_defaults, namespaces,
                                       max_depth, extra_validator):
@@ -955,7 +955,7 @@ def decode(self, obj: ST, validation: str = 'strict', **kwargs: Any) -> DecodeTy
         a simple data type object otherwise. If *validation* argument is 'lax' a 2-items \
         tuple is returned, where the first item is the decoded object and the second item \
         is a list containing the errors.
-        :raises: :exc:`XMLSchemaValidationError` if the object is not decodable by \
+        :raises: :exc:`xmlschema.XMLSchemaValidationError` if the object is not decodable by \
         the XSD component, or also if it's invalid when ``validation='strict'`` is provided.
         """
         check_validation_mode(validation)
@@ -983,8 +983,8 @@ def encode(self, obj: Any, validation: str = 'strict', **kwargs: Any) -> EncodeT
         a string if it's simple type datum. If *validation* argument is 'lax' a 2-items \
         tuple is returned, where the first item is the encoded object and the second item \
         is a list containing the errors.
-        :raises: :exc:`XMLSchemaValidationError` if the object is not encodable by the XSD \
-        component, or also if it's invalid when ``validation='strict'`` is provided.
+        :raises: :exc:`xmlschema.XMLSchemaValidationError` if the object is not encodable by \
+        the XSD component, or also if it's invalid when ``validation='strict'`` is provided.
         """
         check_validation_mode(validation)
         result, errors = None, []