documentation added

README.rst

@@ -14,7 +14,7 @@ paxb
 
 
 Python Architecture for XML Binding
-===================================
+-----------------------------------
 
 paxb is a library that provides an API for mapping between XML documents and Python objects.
 
@@ -33,7 +33,7 @@ API can be mixed together.
 
 
 Installation
-============
+------------
 
 You can install paxb with pip:
 
@@ -43,13 +43,19 @@ You can install paxb with pip:
 
 
 Requirements
-============
+------------
 
 - `attrs <https://www.attrs.org/en/stable/index.html>`_
 
 
+Documentation
+-------------
+
+Documentation is available at `readthedocs <https://paxb.readthedocs.io/en/latest/>`_.
+
+
 Quick start
-===========
+-----------
 
 user.xml:
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,4 @@
+.. _api:
+
+Developer Interface
+===================

docs/attrs.rst

@@ -0,0 +1,119 @@
+.. _attrs:
+
+attrs library integration
+=========================
+
+As soon as paxb is based on `attrs <https://www.attrs.org/en/stable/index.html>`_ library paxb and attrs
+APIs can be mixed together.
+
+
+Decorator :py:func:`@model` accepts `attr.s <https://www.attrs.org/en/stable/api.html#attr.s>`_ function arguments as ``**kwargs`` and internally passes them to it. For example you can pass ``str=True`` argument to ask ``attrs`` library to generate ``__str__`` method for a class.
+
+
+Functions :py:func:`attribute`, :py:func:`field` and :py:func:`nested` accept `attr.ib <https://www.attrs.org/en/stable/api.html#attr.ib>`_ function arguments as ``**kwargs`` and internally passes them to it. For example you can pass ``default`` or ``factory`` argument to set a default value for a class field or ``converter`` argument to convert a value to an appropriate type. Look at the example:
+
+.. code-block:: python
+
+	>>> @model
+	... class Model:
+	...     field = field(default='1', converter=int)
+	...
+	>>> print(Model())
+	Model(field=1)
+
+
+paxb in conjuction with attrs library can be used as a flexible xml-to-json converter and vise versa. All you need is just to declare a model, fields and field types, the rest is up to paxb.
+
+Suppose you have an xml document ``user.xml``:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="utf-8"?>
+    <doc:envelope xmlns:doc="http://www.test1.org">
+        <doc:user name="Alexey" surname="Ivanov" age="26">
+
+            <doc:contacts>
+                <doc:phone>+79204563539</doc:phone>
+                <doc:email>alex@gmail.com</doc:email>
+                <doc:email>alex@mail.ru</doc:email>
+            </doc:contacts>
+
+            <data:occupations xmlns:data="http://www.test2.org">
+                <data:occupation title="yandex">
+                    <data:address>Moscow</data:address>
+                    <data:employees>8854</data:employees>
+                </data:occupation>
+                <data:occupation title="skbkontur">
+                    <data:address>Yekaterinburg</data:address>
+                    <data:employees>7742</data:employees>
+                </data:occupation>
+            </data:occupations>
+
+        </doc:user>
+    </doc:envelope>
+
+
+- First you need to describe a model:
+
+.. code-block:: python
+
+    @pb.model(name="occupation")
+    class Occupation:
+        title = pb.attr()
+        address = pb.field()
+        employees = pb.field(converter=int)
+
+    @pb.model(name="user", ns="doc")
+    class User:
+        name = pb.attr()
+        surname = pb.attr()
+        age = pb.attr(converter=int)
+
+        phone = pb.wrap("contacts", pb.field())
+        emails = pb.wrap("contacts", pb.as_list(pb.field(name="email")))
+
+        occupations = pb.wrap("occupations", pb.lst(pb.nested(Occupation)), ns="data")
+
+
+- Then deserialize a docuemnt:
+
+.. code-block:: python
+
+    with open("user.xml") as file:
+        xml = file.read()
+
+    user = pb.from_xml(User, xml, envelope="doc:envelope", ns_map={
+    	"doc": "http://www.test1.org",
+    	"data": "http://www.test2.org",
+    })
+
+- Call `asdict <https://www.attrs.org/en/stable/api.html#attr.asdict>`_ attrs API method:
+
+.. code-block:: python
+
+	with open("user.json") as file:
+	    json.dump(attr.asdict(user), file)
+
+- Serialized user file ``user.json``:
+
+.. code-block:: json
+
+    {
+    	"name": "Alexey",
+        "surname": "Ivanov",
+        "age": 26,
+        "phone": "+79204563539",
+        "emails": ["alex@gmail.com", "alex@mail.ru"],
+        "occupations": [
+            {
+                "title": "yandex",
+                "address": "Moscow",
+                "employees": 8854
+            },
+            {
+                "title": "skbkontur",
+                "address": "Yekaterinburg",
+                "employees": 7742
+            }
+        ]
+    }