docs: overhaul and add readthedocs support.

Resolves #32, resolves #33.

.readthedocs.yml

@@ -0,0 +1,13 @@
+version: 2
+formats: all
+build:
+  os: ubuntu-20.04
+  tools:
+    python: '3.10'
+python:
+  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/contributing.rst

@@ -0,0 +1,30 @@
+Contributing
+============
+
+Contributions to the project can take many forms.
+
+Document missing features
+-------------------------
+
+I won't even pretend to understand the XML/XSD semantics completely so there is a good chance I missed something.
+
+You can help by submitting examples of XML (with the according schema) which soapfish currently can not handle. Ideally
+you'd write a unit test which clearly demonstrates the failure.
+
+Please try to minimize the sample as much as possible. We know this can be time-consuming but otherwise another
+developer has to do it, taking away precious development time.
+
+Implement missing features
+--------------------------
+
+Well, of course that's most helpful.
+
+Some advice about the order in which new features should be implemented:
+
+#. Ensure that you can express the XSD schema using the classes from ``soapfish.xsdspec``. This is the actual schema
+   representation without any semantic sugar.
+#. Build your schema in soapfish.xsd elements which is the high-level API. Try to build the object graph as you need.
+#. Ensure that the assigned values in the object graph can be parsed and serialized to XML.
+#. Implement XSD generation using your object graph.
+#. Implement code-generation based on a pre-built XSD representing your use-case.
+

docs/index.rst

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