Issue 84 apidocjs

docs/docgen.rst

@@ -9,3 +9,108 @@ 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.
+
+
+Generation using apidocjs
+-------------------------
+
+The **apidocjs** it's an Inline Documentation for RESTful web APIs it can be used to declare and presents in an elegant way the specifications of your REST API.
+
+
+How it works
+============
+
+The **apidoc** recursively scan the input directory for code source containing comments (classes, methods and/or functions) that starts with line **@api**. Like:
+
+.. code-block:: python
+
+    """
+    @api {get} /user/:id Request User information
+    @apiName GetUser
+    @apiGroup User
+
+    @apiParam {Number} id Users unique ID.
+
+    @apiSuccess {String} firstname Firstname of the User.
+    @apiSuccess {String} lastname  Lastname of the User.
+    """
+
+To avoid re-declare the API specifications (Schemas and Examples) Tornado-JSON apidocjs helper recreate some dummy python files containing the declared urls, schemas and examples this data is default stored on the **apidocjs_input** directory.
+
+It's very **important** to keep these files versioned like regular code.
+
+
+Versioning your docs (keep it)
+==============================
+
+To keep versions of your documentation (output directory *doc*) you must keep the initial generated input dummy data (*apidoc_jsinput/* directory files)
+
++ apidocjs_input
+    - defaults.py
+    - 0.0.1
+        - apidoc.json
+        - team_playerhandler.py
+        - team_gamehandler.py
+
+
+Requirements / installation  apidocjs
+=====================================
+
+Its necessary to have the **apidoc** command on your current *$PATH*, to install it just do:
+
+.. code-block:: bash
+
+    npm install apidoc -g
+
+
+If you have any problem on the installation or using it, check this link:
+
+`Install Instructions <http://apidocjs.com/#install>`_.
+
+
+
+Usage
+=====
+
+Use the **apidocjs** parameter on
+
+.. autoclass:: tornado_json.application.Application
+
+
+.. code-block:: python
+
+    from tornado_json.application import Application
+
+    application = Application(routes=routes,
+                              apidocjs={
+                                  name: "My Project",
+                                  title: "My Projecto Title",
+                                  # Default initial version
+                                  version: '0.0.1',
+                                  # Current Version API Endpoint
+                                  url: "https://api.example.com/v1"})
+
+
+More information about thoses pameters you can find at
+
+`Configuration <http://apidocjs.com/#configuration>`_.
+
+
+
+Caveats
+=======
+
+list of **types**
+^^^^^^^^^^^^^^^^^
+
+Looks like *Draft4Validator* (jsonschema's default) allow multiple values on
+"type" definition, as first solution ignore the "null" type and get
+the first type to be used on @apiParam/@apiSuccess declaration.
+
+The code below will be threated on the output doc as **string** type.
+
+.. code-block:: javascript
+
+    {
+        type: ['null', 'string', 'number']
+    }