docs: A few modifications and corrections

docs/clients.rst

@@ -1,5 +1,5 @@
-Create client-side applications
-*******************************
+Client-Side Applications
+************************
 
 APIMAS supports the creation of client-side applications to interact
 with the REST API described by your specification. There is a

docs/drf_adapter.rst

@@ -1,5 +1,5 @@
-Create server-side applications
-*******************************
+Django Applications
+*******************
 
 You can easily build a server-side application by using an APIMAS
 backend. Currently, the only backend supported is ``apimas-drf``
@@ -250,6 +250,7 @@ typical example a developer has to make the following classes:
         number = models.IntegerField()
 
 ``forms.py``
+
 .. code-block:: python
 
     from django import forms
@@ -262,6 +263,7 @@ typical example a developer has to make the following classes:
             fields = ('number', 'text',)
 
 ``views.py``
+
 .. code-block:: python
 
    import json
@@ -995,45 +997,45 @@ Predicate           Description
                     backend.
 
                     **Parameters**:
-                        `model`: String of the django-model corresponding to
+                        ``model``: String of the django-model corresponding to
                         the storage representation of the collection.
 
-                        `authentication_classes`: (optional) List of classes
+                        ``authentication_classes``: (optional) List of classes
                         used for the authentication of the collection.
                         More `here <http://www.django-rest-framework.org/api-guide/authentication/>`__.
 
-                        `permission_classes`: (optional) List of the classes
+                        ``permission_classes``: (optional) List of the classes
                         responsible for the permissions of the collection.
                         More `here <http://www.django-rest-framework.org/api-guide/permissions/>`__.
 
-                        `mixins`: (optional) List of the bases classes of
+                        ``mixins``: (optional) List of the bases classes of
                         the ``ViewSet`` class generated by django-rest adapter.
 
-                        `model_serializers`: (optional) List of bases classes
+                        ``model_serializers``: (optional) List of bases classes
                         of the ``ApimasModelSerializer`` (class responsible when
                         having model-fields) generated by django-rest adapter.
 
-                        `serializers`: (optional) List of base classes of
+                        ``serializers``: (optional) List of base classes of
                         the ``ApimasSerializer`` (class responsible when
                         having non-model fields) generated by django-rest adapter.
 
-                        `hook_class`: (optional) A class which implements hooks
+                        ``hook_class``: (optional) A class which implements hooks
                         before and after interacting with db for various actions.
-                        See `more <#customizing-your-application>`__.
+                        See `more <#customize-your-application>`__.
 
 ``.drf_field``      The parent node is a drf_field. In other words, it is an
                     instance of a django-rest-framework field which is responsible
                     for converting raw value of a field (sent by client) into
                     complex data such as objects, querysets, etc.
 
                     **Parameters**:
-                        `onmodel`: True if field has a storage representation,
+                        ``onmodel``: True if field has a storage representation,
                         False otherwise (default: True).
 
-                        `source`: Name of the storage representation of
+                        ``source``: Name of the storage representation of
                         the field (Default is the name of the parent).
 
-                        `instance_source`: A string which points to a function
+                        ``instance_source``: A string which points to a function
                         which retrieves the value of the field given the
                         current instance (applicable if ``onmodel: False``). 
 =================== =====================================================================================

docs/index.rst

@@ -4,43 +4,57 @@
 APIMAS - API Modeling and Serving
 *********************************
 
-Install
-=======
-As a starting point, create a `virtualenv <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`__:
+APIMAS provides a flexible way for building, modifying and
+extending your application without the cumbersome management
+due to the complexity and the size of it.
 
-.. code-block:: shell
+Trying it out
+=============
+
+apimas
+------
+
+Explore apimas package to find out how to model your REST API, and
+build and deploy your application.
+
+
+First, create a `virtualenv <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`__:
+
+.. code-block:: console
 
     virtualenv virtualenv-apimas
     source virtualenv-apimas/bin/activate
 
+then, install apimas via `pip <https://pip.pypa.io/en/stable/>`__:
 
-Now, you can easily install apimas via ``pip``. Run the following
-command:
-
-.. code-block:: shell
+.. code-block:: console
 
     pip install apimas
 
-Alternatively, install apimas from github repository:
+apimas-drf
+----------
+
+For apimas support for building django applications,
+you should checkout apimas-drf package. 
+
+In a virtualenv run:
 
-.. code-block:: shell
+.. code-block:: console
 
-    git clone https://github.com/grnet/apimas
-    cd apimas/apimas
-    python setup.py install
+    pip install apimas-drf
 
 
 Contents
 ========
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 4
 
 
-   basic_architecture
+   overview
    specification
-   writing_spec
    predicates
+   writing_spec
    drf_adapter
    clients
    license

docs/basic_architecture.rst → docs/overview.rst

@@ -1,5 +1,5 @@
-Basic Architecture
-==================
+Overview
+========
 
 APIMAS assumes applications are set up like this:
 
@@ -72,8 +72,8 @@ APIMAS assumes applications are set up like this:
      them top-level. Nested collections are supported to help data
      organization and convenience.
 
-Built-in operations can be overridden for customization.
-The application may also create new named actions:
+     Built-in operations can be overridden for customization.
+     The application may also create new named actions:
 
    - ``POST /<prefix>/api/<resource>/<id>/actions/<action>  data:{key:val...}``
 

docs/predicates.rst

@@ -57,15 +57,16 @@ Predicate         Description
                   PUT    <collection name>/<pk>/
                   PATCH  <collection name>/<pk>/
 
-                  **Note**: The ``.update`` predicate allows a single resource
-                  to be both replaced and partially updated.
-
 ``.delete``       A single resource can be deleted from the set of existing.
                   It corresponds to:
 
                   DELETE <collection name>/<pk>/
 ================= =================================================================
 
+.. note::
+    The ``.update`` predicate allows a single resource
+    to be both replaced and partially updated.
+
 Action predicates are specified inside the structural element **actions** of
 a collection definition.
 
@@ -111,7 +112,7 @@ Predicate         Description
                   supported.
 
                   **Parameters**:
-                      `maxlength`: The upper bound of string's size (optional).
+                      ``maxlength``: The upper bound of string's size (optional).
                       The default is 255.
 ``.text``         Parent node is a text.
 ``.boolean``      Parent node is either true or false.
@@ -120,44 +121,49 @@ Predicate         Description
 ``.choices``      Parent node can take a list of allowed values as specified
                   by the parameter ``allowed``.
 
+                      **Example**:
+
                       .. code-block:: python
 
-                          'foo': {
-                              '.choices': {
-                                  'allowed': [1, 'bar']
-                              }
-                          }
+                        'foo': {
+                            '.choices': {
+                                'allowed': [1, 'bar']
+                            }
+                        }
+
                       Parent node can be either 1 or 'bar'.
 
                   **Parameters**:
-                      `allowed`: A list of acceptable values for the parent.
+                      ``allowed``: A list of acceptable values for the parent.
+                      (Each item **must** be a literal).
 
-                      `display`: A list  of the displayed values of the node.
+                      ``display``: A list  of the displayed values of the node
+                      (optional). By default is the same as ``allowed``.
 
 ``.ref``          Parent node points to the web location of another resource.
 
                   **Parameters**:
-                      `to`:   Name of the collection where resource is located.
-                              This must be a valid name of a collection which
-                              have been specified on APIMAS specification too.
-                      `many`: true if parent node points to multiple resources,
-                              false otherwise.
+                      ``to``: Name of the collection where resource is located.
+                      This must be a valid name of a collection which
+                      have been specified on APIMAS specification too.
+
+                      ``many``: true if parent node points to multiple resources,
+                      false otherwise.
 ``.identity``     Parent node points to the web location of this resource.
                   It's actually the REST identifier of the resource. It is
                   non-writable.
 ``.file``         Parent node is a file.
 ``.date``         Parent node is a date, represented by a string.
 
-
                   **Parameters**:
-                      `format`:  A list of string representing the allowed
+                      ``format``:  A list of string representing the allowed
                       input formats of the date. (optional).
                       By default only `ISO-8601 <http://www.iso.org/iso/home/standards/iso8601.htm>`__
                       is allowed.
 ``.datetime``     Parent node is a datetime, represented by a string.
 
                   **Parameters**:
-                      `format`:  A list of strings representing the allowed.
+                      ``format``:  A list of strings representing the allowed.
                       input formats of the datetime.
                       By default only `ISO-8601 <http://www.iso.org/iso/home/standards/iso8601.htm>`__
                       is allowed.
@@ -190,7 +196,7 @@ Predicate         Description
 ================= =================================================================
 ``.required``     The parent node is required and **must** be included in every
                   API call associated with create and update operations
-                  (POST and PUT requests).
+                  (e.g. POST and PUT requests).
 ``.readonly``     The parent node is read-only and its value can be viewed, but
                   it cannot be modified or set.
 ``.writeonly``    The parent node is write-only and its value can be modified

docs/specification.rst

@@ -1,7 +1,7 @@
 .. _specification:
 
-Introduction to APIMAS specification
-====================================
+APIMAS Specification
+====================
 
 APIMAS considers interfaces made from a hierarchy of
 Collections, Resources, and Properties.