Skip to content

Commit dff120f

Browse files
ngnpopengnpope
committed
docs: overhaul and add readthedocs support.
Resolves #33.
1 parent d9a41a8 commit dff120f

11 files changed

+153
-168
lines changed

‎.readthedocs.yml

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
version: 2
2+
formats: all
3+
python:
4+
version: 3.9
5+
install:
6+
- requirements: docs/requirements.txt
7+
sphinx:
8+
builder: html
9+
configuration: docs/conf.py
10+
fail_on_warning: true

‎INFORMATION.md

-28
This file was deleted.

‎LIMITATIONS.md

-99
This file was deleted.

‎docs/conf.py

+3-32
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,5 @@
1-
# Soapfish documentation build configuration file, created by
2-
# sphinx-quickstart on Thu Mar 6 16:06:14 2014.
3-
#
4-
# This file is execfile()d with the current directory set to its
5-
# containing dir.
6-
#
7-
# Note that not all possible configuration values are present in this
8-
# autogenerated file.
9-
#
10-
# All configuration values have a default; values that are commented out
11-
# serve to show the default.
12-
13-
# If extensions (or modules to document with autodoc) are in another directory,
14-
# add these directories to sys.path here. If the directory is relative to the
15-
# documentation root, use os.path.abspath to make it absolute, like shown here.
16-
# sys.path.insert(0, os.path.abspath('.'))
17-
18-
# -- General configuration ------------------------------------------------
19-
20-
# If your documentation needs a minimal Sphinx version, state it here.
21-
# needs_sphinx = '1.0'
22-
23-
# Add any Sphinx extension module names here, as strings. They can be
24-
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
25-
# ones.
261
extensions = [
27-
'sphinx.ext.todo',
2+
'sphinx.ext.intersphinx',
283
'sphinx.ext.viewcode',
294
]
305

@@ -97,15 +72,11 @@
9772
# If true, keep warnings as "system message" paragraphs in the built documents.
9873
# keep_warnings = False
9974

100-
# If true, `todo` and `todoList` produce output, else they produce nothing.
101-
todo_include_todos = False
102-
103-
10475
# -- Options for HTML output ----------------------------------------------
10576

10677
# The theme to use for HTML and HTML Help pages. See the documentation for
10778
# a list of builtin themes.
108-
html_theme = 'alabaster'
79+
html_theme = 'sphinx_rtd_theme'
10980

11081
# Theme options are theme-specific and customize the look and feel of a theme
11182
# further. For a list of options available for each theme, see the
@@ -134,7 +105,7 @@
134105
# Add any paths that contain custom static files (such as style sheets) here,
135106
# relative to this directory. They are copied after the builtin static files,
136107
# so a file named "default.css" will overwrite the builtin "default.css".
137-
html_static_path = ['_static']
108+
html_static_path = []
138109

139110
# Add any extra paths that contain custom files (such as robots.txt or
140111
# .htaccess) here, relative to this directory. These files are copied

‎docs/index.rst

+2
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ Contents:
88

99
tutorial
1010
middlewares
11+
limitations
12+
specifications
1113

1214
Indices and tables
1315
==================

‎docs/limitations.rst

+103
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
Limitations
2+
===========
3+
4+
``xsd.Ref()`` is not serialized
5+
-------------------------------
6+
7+
XML schema references are not serialized. Below is an example of code that does not generate a valid schema:
8+
9+
.. code-block:: python
10+
11+
from lxml import etree
12+
from soapfish import py2xsd, xsd
13+
14+
class Person(xsd.Group):
15+
name = xsd.Element(xsd.String)
16+
surname = xsd.Element(xsd.String)
17+
18+
class Job(xsd.ComplexType):
19+
title = xsd.Element(xsd.String)
20+
person = xsd.Ref(Person)
21+
22+
schema = xsd.Schema(
23+
imports=[],
24+
targetNamespace='http://example.com/ws/spec',
25+
elementFormDefault='qualified',
26+
simpleTypes=[],
27+
attributeGroups=[],
28+
groups=[],
29+
complexTypes=[],
30+
elements={'job': xsd.Element(Job())},
31+
)
32+
33+
print(etree.tostring(py2xsd.generate_xsd(schema), pretty_print=True))
34+
35+
Incorrect XML Schema:
36+
37+
.. code-block:: xml
38+
39+
<xsd:schema
40+
xmlns:sns="http://example.com/ws/spec"
41+
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
42+
targetNamespace="http://example.com/ws/spec"
43+
elementFormDefault="qualified">
44+
<xsd:element name="job">
45+
<xsd:complexType>
46+
<xsd:sequence>
47+
<xsd:element name="title" type="xsd:string" minOccurs="1" nillable="false"/>
48+
</xsd:sequence>
49+
</xsd:complexType>
50+
</xsd:element>
51+
</xsd:schema>
52+
53+
Expected XML Schema:
54+
55+
.. code-block:: xml
56+
57+
<xsd:schema
58+
xmlns:site="http://example.com/ws/spec"
59+
xmlns:xs="http://www.w3.org/2001/XMLSchema"
60+
targetNamespace="http://example.com/ws/spec"
61+
elementFormDefault="qualified">
62+
<xsd:element name="person">
63+
<xsd:complexType>
64+
<xsd:sequence>
65+
<xsd:element name="name" type="xs:string"/>
66+
<xsd:element name="surname" type="xs:string"/>
67+
</xsd:sequence>
68+
</xsd:complexType>
69+
</xsd:element>
70+
<xsd:element name="job">
71+
<xsd:complexType>
72+
<xsd:sequence>
73+
<xsd:element name="title" type="xs:string" minOccurs="1" nillable="false"/>
74+
<xsd:element ref="site:person"/>
75+
</xsd:sequence>
76+
</xsd:complexType>
77+
</xsd:element>
78+
</xsd:schema>
79+
80+
Valid XML for Expected Schema:
81+
82+
.. code-block:: xml
83+
84+
<?xml version="1.0" encoding="utf-8" standalone="no"?>
85+
<job xmlns="http://example.com/ws/spec">
86+
<title>Software Developer</title>
87+
<person>
88+
<name>Joe</name>
89+
<surname>Bloggs</surname>
90+
</person>
91+
</job>
92+
93+
``XSDDate`` does not support full date range
94+
--------------------------------------------
95+
96+
The XML schema specification does not limit the range of dates representable by
97+
``xs:date``. For example, the values ``-2000-03-10`` and ``20000-04-20`` are
98+
valid as far ``xs:date`` is concerned. Currently ``soapfish.xsd_types.XSDDate``
99+
is subclassing Python's standard library :py:class:`datetime.date` which has a
100+
much more narrow definition.
101+
102+
Very likely the best solution will be to back our implementation with an
103+
alternative ``date`` implementation.

‎docs/middlewares.rst

-8
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,16 @@
11
Middlewares
22
===========
33

4-
54
Middlewares Overview
65
--------------------
76

87
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.
98

10-
119
Middlewares Architecture
1210
''''''''''''''''''''''''
1311

1412
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.
1513

16-
1714
Dispatcher Reference
1815
''''''''''''''''''''
1916

@@ -31,7 +28,6 @@ The purpose of a middleware is to inspect, analyze, or modify the application en
3128
3229
Changes made to the environment, request, and response objects will propagate immediately throughout the application and its other middleware layers.
3330

34-
3531
Next Middleware Reference
3632
'''''''''''''''''''''''''
3733

@@ -42,14 +38,12 @@ Each middleware layer also has a reference to the next inner middleware layer to
4238
def my_middleware(request, next_call):
4339
return next_call(request) # optionally call the next middleware
4440
45-
4641
How to Use Middleware
4742
---------------------
4843

4944
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.
5045
This is also possible to add middlewares by modifying the list `dispatcher.middlewares`.
5146

52-
5347
Example Middleware
5448
''''''''''''''''''
5549

@@ -69,7 +63,6 @@ This example middleware will log the client IP address.
6963
# call next middleware
7064
return next_call(request)
7165
72-
7366
Add Middleware
7467
''''''''''''''
7568

@@ -83,7 +76,6 @@ Add Middleware
8376
# add an inside middleware
8477
dispatcher.middlewate.append(get_client_address)
8578
86-
8779
When the example dispatcher above is invoked, the client IP address will be logged.
8880

8981
How to Write Middleware

‎docs/requirements.txt

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
sphinx
2+
sphinx-rtd-theme

0 commit comments

Comments
 (0)