docs: overhaul and add readthedocs support.

Resolves #33.

.readthedocs.yml

@@ -0,0 +1,10 @@
+version: 2
+formats: all
+python:
+  version: 3.9
+  install:
+  - requirements: docs/requirements.txt
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+  fail_on_warning: true

docs/conf.py

@@ -1,30 +1,5 @@
-# Soapfish documentation build configuration file, created by
-# sphinx-quickstart on Thu Mar  6 16:06:14 2014.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# 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.
-# sys.path.insert(0, os.path.abspath('.'))
-
-# -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.0'
-
-# 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.todo',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
 ]
 
@@ -97,15 +72,11 @@
 # If true, keep warnings as "system message" paragraphs in the built documents.
 # keep_warnings = False
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
-
 # -- 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'
+html_theme = 'sphinx_rtd_theme'
 
 # 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
@@ -134,7 +105,7 @@
 # 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']
+html_static_path = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/index.rst

@@ -8,6 +8,8 @@ Contents:
 
     tutorial
     middlewares
+    limitations
+    specifications
 
 Indices and tables
 ==================

docs/limitations.rst

@@ -0,0 +1,103 @@
+Limitations
+===========
+
+``xsd.Ref()`` is not serialized
+-------------------------------
+
+XML schema references are not serialized. Below is an example of code that does not generate a valid schema:
+
+.. code-block:: python
+
+   from lxml import etree
+   from soapfish import py2xsd, xsd
+
+   class Person(xsd.Group):
+       name = xsd.Element(xsd.String)
+       surname = xsd.Element(xsd.String)
+
+   class Job(xsd.ComplexType):
+       title = xsd.Element(xsd.String)
+       person = xsd.Ref(Person)
+
+   schema = xsd.Schema(
+       imports=[],
+       targetNamespace='http://example.com/ws/spec',
+       elementFormDefault='qualified',
+       simpleTypes=[],
+       attributeGroups=[],
+       groups=[],
+       complexTypes=[],
+       elements={'job': xsd.Element(Job())},
+   )
+
+   print(etree.tostring(py2xsd.generate_xsd(schema), pretty_print=True))
+
+Incorrect XML Schema:
+
+.. code-block:: xml
+
+   <xsd:schema
+       xmlns:sns="http://example.com/ws/spec"
+       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+       targetNamespace="http://example.com/ws/spec"
+       elementFormDefault="qualified">
+     <xsd:element name="job">
+       <xsd:complexType>
+         <xsd:sequence>
+           <xsd:element name="title" type="xsd:string" minOccurs="1" nillable="false"/>
+         </xsd:sequence>
+       </xsd:complexType>
+     </xsd:element>
+   </xsd:schema>
+
+Expected XML Schema:
+
+.. code-block:: xml
+
+   <xsd:schema
+       xmlns:site="http://example.com/ws/spec"
+       xmlns:xs="http://www.w3.org/2001/XMLSchema"
+       targetNamespace="http://example.com/ws/spec"
+       elementFormDefault="qualified">
+     <xsd:element name="person">
+       <xsd:complexType>
+         <xsd:sequence>
+           <xsd:element name="name" type="xs:string"/>
+           <xsd:element name="surname" type="xs:string"/>
+         </xsd:sequence>
+       </xsd:complexType>
+     </xsd:element>
+     <xsd:element name="job">
+       <xsd:complexType>
+         <xsd:sequence>
+           <xsd:element name="title" type="xs:string" minOccurs="1" nillable="false"/>
+           <xsd:element ref="site:person"/>
+         </xsd:sequence>
+       </xsd:complexType>
+     </xsd:element>
+   </xsd:schema>
+
+Valid XML for Expected Schema:
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="utf-8" standalone="no"?>
+   <job xmlns="http://example.com/ws/spec">
+     <title>Software Developer</title>
+     <person>
+       <name>Joe</name>
+       <surname>Bloggs</surname>
+     </person>
+   </job>
+
+``XSDDate`` does not support full date range
+--------------------------------------------
+
+The XML schema specification does not limit the range of dates representable by
+``xs:date``.  For example, the values ``-2000-03-10`` and ``20000-04-20`` are
+valid as far ``xs:date`` is concerned. Currently ``soapfish.xsd_types.XSDDate``
+is subclassing Python's standard library :py:class:`datetime.date` which has a
+much more narrow definition.
+
+Very likely the best solution will be to back our implementation with an
+alternative ``date`` implementation.

docs/middlewares.rst

@@ -1,19 +1,16 @@
 Middlewares
 ===========
 
-
 Middlewares Overview
 --------------------
 
 The soapfish library implements a version of the Rack protocol. As a result, a soapfish dispatcher can have middlewares that may inspect, analyze, or modify the application environment, request, and response before and/or after the method call.
 
-
 Middlewares Architecture
 ''''''''''''''''''''''''
 
 Think of a soapfish dispatcher as an onion. Each layer of the onion is a middleware. When you invoke the dispatcher dispatch() method, the outer-most middleware layer is invoked first. When ready, that middleware layer is responsible for optionally invoking the next middleware layer that it surrounds. This process steps deeper into the onion - through each middleware layer - until the service method is invoked. This stepped process is possible because each middleware layer are callable. When you add new middleware to the dispatcher, the added middleware will become a new outer layer and surround the previous outer middleware layer (if available) or the service method call itself.
 
-
 Dispatcher Reference
 ''''''''''''''''''''
 
@@ -31,7 +28,6 @@ The purpose of a middleware is to inspect, analyze, or modify the application en
 
 Changes made to the environment, request, and response objects will propagate immediately throughout the application and its other middleware layers.
 
-
 Next Middleware Reference
 '''''''''''''''''''''''''
 
@@ -42,14 +38,12 @@ Each middleware layer also has a reference to the next inner middleware layer to
     def my_middleware(request, next_call):
         return next_call(request)  # optionally call the next middleware
 
-
 How to Use Middleware
 ---------------------
 
 On the dispatcher instantiation, use the `middlewares` parameter to give a list of middleware, the first middleware in the list will be called first, it is the outer onion.
 This is also possible to add middlewares by modifying the list `dispatcher.middlewares`.
 
-
 Example Middleware
 ''''''''''''''''''
 
@@ -69,7 +63,6 @@ This example middleware will log the client IP address.
         # call next middleware
         return next_call(request)
 
-
 Add Middleware
 ''''''''''''''
 
@@ -83,7 +76,6 @@ Add Middleware
     # add an inside middleware
     dispatcher.middlewate.append(get_client_address)
 
-
 When the example dispatcher above is invoked, the client IP address will be logged.
 
 How to Write Middleware

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx-rtd-theme