Add readthedocs documentation

docs/docgen.rst

@@ -0,0 +1,11 @@
+========================
+Documentation Generation
+========================
+
+Public API Usage Documentation
+------------------------------
+
+API Usage documentation is generated by the ``tornado_json.api_doc_gen``
+module. The ``api_doc_gen`` method is run on startup so to generate
+documentation, simply run your app and the documentation will written to
+``API_Documentation.md``. in the current folder.

docs/index.rst

@@ -9,8 +9,11 @@ Welcome to tornado_json's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
 
+   installation
+   requesthandler_guidelines
+   docgen
    tornado_json
 
 
@@ -20,4 +23,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/installation.rst

@@ -0,0 +1,11 @@
+============
+Installation
+============
+
+Simply run::
+
+    pip install Tornado-JSON
+
+Alternatively, clone the GitHub repository (default branch is `dev`)::
+
+    git clone https://github.com/hfaran/Tornado-JSON.git

docs/requesthandler_guidelines.rst

@@ -0,0 +1,62 @@
+==========================
+Request Handler Guidelines
+==========================
+
+Schemas and Public API Documentation
+------------------------------------
+
+Create an ``apid`` dict in each RequestHandler as a class-level
+variable, i.e.,
+
+.. code:: python
+
+    class ExampleHandler(APIHandler):
+        apid = {}
+
+For each HTTP method you implement, add a corresponding entry in
+``apid``. The schemas must be valid JSON schemas;
+`readthedocs <https://python-jsonschema.readthedocs.org/en/latest/>`__
+for an example. Here is an example for POST:
+
+.. code:: python
+
+    apid["post"] = {
+        "input_schema": ...,
+        "output_schema": ...,
+        "doc": ...,
+    }
+
+``doc`` is the **public** accompanying documentation that will be
+available on the wiki.
+
+Use the ``io_schema`` decorator on methods which will automatically
+validate the request body and output against the schemas in
+``apid[method_name]``. Additionally, ``return`` the data from the
+request handler, rather than writing it back (the decorator will take
+care of that).
+
+.. code:: python
+
+    class ExampleHandler(APIHandler):
+        @io_schema
+        def post(self, body):
+            ...
+            return data
+
+
+Assertions
+----------
+
+
+Use ``utils.api_assert`` to fail when some the client does not meet some
+API pre-condition/requirement, e.g., an invalid or incomplete request is
+made. When using an assertion is not suitable,
+``raise APIError( ... )``; don't use JSend ``fail`` directly.
+
+.. code:: python
+
+    class ExampleHandler(APIHandler):
+        @io_schema
+        def post(self, body):
+            ...
+            api_assert(condition, status_code, log_message=log_message)