Merge remote-tracking branch 'origin/doc_style_guide' into 1.6

Conflicts:
	doc/sphinx/dev_guide/building_documentation.rst

doc/sphinx/dev_guide/building_documentation.rst

 .. _building-documentation:
 
 -------------------------------------------------------------------------------
-                             Building Documentation
+Building documentation
 -------------------------------------------------------------------------------
 
-After building and testing your local instance of Tarantool, you can build a local version of this documentation and contribute to it. 
+After building and testing your local instance of Tarantool, you can build a
+local version of this documentation and contribute to it.
 
-Documentation is based on the Python-based Sphinx generator. So, make sure to
+Documentation is based on the Python-based Sphinx generator. So, make sure
 install all Python modules indicated in the :ref:`building-from-source` section
 of this documentation. The procedure below implies that you already took those
 steps and successfully tested your instance of Tarantool.
@@ -18,36 +19,55 @@ procedure is similar for other supported platforms):
 
    .. code-block:: bash
 
-    cd ~/tarantool
-    cmake -DENABLE_DOC=TRUE
-    make -C doc
+    cd ~/tarantool cmake -DENABLE_DOC=TRUE make -C doc
 
 Documentation is created and stored at ``doc/www/output``.
 
-2. Set up a web-server. 
+2. Set up a web-server.
 
-Note that if your Tarantool Database runs on a Virtual machine, you need to make sure that your host and client machines operate in the same network, i.e., to configure port forwarding. If you use Oracle VM VirtualBox, follow the guidelines below:
+Note that if your Tarantool Database runs on a Virtual machine, you need to make
+sure that your host and client machines operate in the same network, i.e., to
+configure port forwarding. If you use Oracle VM VirtualBox, follow the
+guidelines below:
+
+* To create a network, navigate to **Network > Advanced > Port Forwarding** in
+  your VirtualBox instance menu.
+  
+* Enable the **Cable connected** checkbox. 
 
-* To create a network, navigate to **Network > Advanced > Port Forwarding** in your VirtualBox instance menu.
-* Enable the **Cable connected** checkbox.
 * Click the **Port Forwarding** button.
-* Set Host and Guest Ports to ``8000``, Host IP to ``127.0.0.1`` and Guest IP to ``10.0.2.15``. Make sure to check the IP of your VB instance, it must be 10.0.2.15 (``ifconfig`` command)
-* Save your settings
 
-If all the prerequisites are met, run the following command to set up a web-server (the example below is based on Ubuntu, but the procedure is similar for other supported platforms). Make sure to run it from the documentation output folder, as specified below:
+* Set Host and Guest Ports to ``8000``, Host IP to ``127.0.0.1`` and Guest
+IP to ``10.0.2.15``. Make sure to check the IP of your VB instance, it must
+be 10.0.2.15 (``ifconfig`` command)
+
+* Save your settings.
+
+If all the prerequisites are met, run the following command to set up a
+web-server (the example below is based on Ubuntu, but the procedure is similar
+for other supported OS's). Make sure to run it from the documentation output
+folder, as specified below:
 
    .. code-block:: bash
 
      cd ~/tarantool/doc/www/output
      python -m SimpleHTTPServer 8000
 
-3. Open your browser and enter ``127.0.0.1:8000`` into the address box. If your local documentation build is valid, the HTML version will be displayed in the browser. 
+3. Open your browser and enter ``127.0.0.1:8000`` into the address box. If your
+local documentation build is valid, the HTML version will be displayed in the
+browser.
+
+To contribute to documentation, use the ``.rst`` format for drafting and submit
+your updates as "Pull Requests" via GitHub.
 
-To contribute to documentation, use the ``.rst`` format for drafting and submit your updates as "Pull Requests" via GitHub. 
+To comply with the writing and formatting style, use guidelines provided in the
+documentation, common sense and existing documents.
 
-To comply with the writing and formatting style, use guidelines provided in the documentation, common sense and existing documents. 
+Note that if you suggest creating a new documentation section (i.e., a whole new
+page), it has to be saved to the relevant section at GitHub.
 
-Note that if you suggest creating a new documentation section (i.e., a whole new page), it has to be saved to the relevant section at GitHub.  
+* Root folder for documentation source files is located at
+  https://github.com/tarantool/tarantool/tree/1.6/doc/sphinx.
 
-* Root folder for documentation source files is located at https://github.com/tarantool/tarantool/tree/1.6/doc/sphinx.
-* Source files for the developers' guide are located at https://github.com/tarantool/tarantool/tree/1.6/doc/sphinx/dev_guide. 
+* Source files for the developers' guide are located at
+  https://github.com/tarantool/tarantool/tree/1.6/doc/sphinx/dev_guide.

doc/sphinx/dev_guide/documentation_guidelines.rst

+-------------------------------------------------------------------------------
+                        Documentation guidelines
+-------------------------------------------------------------------------------
+
+These guidelines are updated on the on-demand basis, covering only those issues
+that cause pains to the existing writers. At this point, we do not aim to come
+up with an exhaustive Documentation Style Guide for the Tarantool project. 
+
+===========================================================
+                        Markup issues
+===========================================================
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                Wrapping text
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The limit is 80 characters per line for plain text, and no limit for any other
+constructions when wrapping affects ReST readability and/or HTML output. Also,
+it makes no sense to wrap text into lines shorter than 80 characters unless you
+have a good reason to do so.
+
+The 80-character limit comes from the ISO/ANSI 80x24 screen resolution, and it's
+unlikely that readers/writers will use 80-character consoles. Yet it's still a
+standard for many coding guidelines (including Tarantool). As for writers, the
+benefit is that an 80-character page guide allows keeping the text window rather
+narrow most of the time, leaving more space for other applications in a
+wide-screen environment.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+              Making comments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes we may need to leave comments in a ReST file. To make sphinx ignore
+some text during processing, use the following per-line notation with ".. //" as
+the comment marker:
+
+.. // your comment here
+
+`The notation example is excluded from HTML output, so please see the source in
+ReST.`
+
+The starting symbols ".. //" do not interfere with the other ReST markup, and
+they are easy to find both visually and using grep. There are no symbols to
+escape in grep search, just go ahead with something like this:
+
+  .. code-block:: console
+
+    grep ".. //" doc/sphinx/dev_guide/*.rst
+
+These comments don't work properly in nested documentation, though (e.g. if you
+leave a comment in module -> object -> method, sphinx ignores the comment and
+all nested content that follows in the method description).
+
+===========================================================
+                Language and style issues
+===========================================================
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+               US vs British spelling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We use English US spelling.
+
+===========================================================
+               Examples and templates
+===========================================================
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+               Module and function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here is an example of documenting a module (``my_fiber``) and a function 
+(``my_fiber.create``).
+
+.. module:: my_fiber
+
+.. function:: create(function [, function-arguments])
+
+    Create and start a ``my_fiber`` object. The object is created and begins to
+    run immediately.
+
+    :param function: the function to be associated with the ``my_fiber`` object
+    :param function-arguments: what will be passed to function
+
+    :return: created ``my_fiber`` object    
+    :rtype: userdata
+
+    **Example:**
+
+    .. code-block:: tarantoolsession
+
+        tarantool> my_fiber = require('my_fiber')
+        ---
+        ...
+        tarantool> function function_name()
+                 >   my_fiber.sleep(1000)
+                 > end
+        ---
+        ...
+        tarantool> my_fiber_object = my_fiber.create(function_name)
+        ---
+        ...
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+               Module, class and method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here is an example of documenting a module (``my_box.index``), a class
+(``my_index_object``) and a function (``my_index_object.rename``).
+
+.. module:: my_box.index
+
+.. class:: my_index_object
+    
+    .. method:: rename(index-name)
+
+        Rename an index.
+                      
+        :param index_object: an object reference
+        :param index_name: a new name for the index (type = string)
+
+        :return: nil
+
+        Possible errors: index_object does not exist.
+
+        **Example:**
+
+        .. code-block:: tarantoolsession
+
+            tarantool> box.space.space55.index.primary:rename('secondary')
+            ---
+            ...
+
+        Complexity Factors: Index size, Index type, Number of tuples accessed.

doc/sphinx/dev_guide/index.rst

@@ -9,6 +9,7 @@
     building_from_source
     building_documentation
     developer_guidelines
+    documentation_guidelines
     box-protocol
     c_style_guide
     python_style_guide