Add couple of chapters and lua domain

doc/sphinx/_templates/layout.html

@@ -5,7 +5,7 @@
 {% block header_scripts %}
   <link rel="stylesheet" href="/doc/_static/sphinx_design.css" />
   <link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
-  <script type="text/javascript" src="../_static/headers.js"></script>
+  <script type="text/javascript" src="/doc/_static/headers.js"></script>
   {{ super() }}
 {% endblock header_scripts %}
 

doc/sphinx/conf.py

@@ -33,8 +33,10 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
-    'ext.filters'
+    'ext.filters',
+    'ext.lua'
 ]
+primary_domain = 'lua'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/sphinx/reference/box/box_schema.rst

+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+                             Package `box.schema`
+-------------------------------------------------------------------------------
+
+.. module:: box.schema
+
+The ``box.schema`` package has one data-definition function: ``space.create()``.
+
+.. function:: space.create(space-name [, {options} ])
+
+    Create a space.
+
+    :param string space-name: name of space, which should not be a number and should not contain special characters
+    :param table options:
+
+    :return: space object
+    :rtype: userdata
+
+    .. container:: table
+
+        **Options for box.schema.space.create**
+
+        +---------------+--------------------+---------+---------------------+
+        | Name          | Effect             | Type    | Default             |
+        +===============+====================+=========+=====================+
+        | temporary     | space is temporary | boolean | false               |
+        +---------------+--------------------+---------+---------------------+
+        | id            | unique identifier  | number  | last space's id, +1 |
+        +---------------+--------------------+---------+---------------------+
+        | field_count   | fixed field count  | number  | 0 i.e. not fixed    |
+        +---------------+--------------------+---------+---------------------+
+        | if_not_exists | no error if        | boolean | false               |
+        |               | duplicate name     |         |                     |
+        +---------------+--------------------+---------+---------------------+
+        | engine        | storage package    | string  | 'memtx'             |
+        +---------------+--------------------+---------+---------------------+
+        | user          | user name          | string  | current user's name |
+        +---------------+--------------------+---------+---------------------+
+
+=================================================
+                    Example
+=================================================
+
+.. code-block:: lua
+
+    tarantool> s = box.schema.space.create('space55')
+    ---
+    ...
+    tarantool> s = box.schema.space.create('space55', {id = 555, temporary = false})
+    ---
+    - error: Space 'space55' already exists
+    ...
+    tarantool> s = box.schema.space.create('space55', {if_not_exists = true})
+    ---
+    ...
+
+After a space is created, usually the next step is to `create an index`_ for it,
+and then it is available for insert, select, and all the other :mod:`box.space`
+functions.
+
+.. _create an index: :func:`box.space.space-name:create_index`

doc/sphinx/reference/box/index.rst

+-------------------------------------------------------------------------------
+                              The `box` library
+-------------------------------------------------------------------------------
+
+As well as executing Lua chunks or defining their own functions, users can exploit
+the Tarantool server's storage functionality with the ``box`` Lua library.
+
+=====================================================================
+                     Packages of the box library
+=====================================================================
+
+The contents of the box library can be inspected at runtime with ``box``, with
+no arguments. The packages inside the box library are:
+
+.. toctree::
+    :maxdepth: 1
+
+    box_schema
+    box_tuple
+    box_space
+    box_index
+    net_box
+    box_cfg
+    box_info
+    box_slab
+    box_stat
+
+Every package contains one or more Lua functions. A few packages contain
+members as well as functions. The functions allow data definition (create
+alter drop), data manipulation (insert delete update select replace), and
+introspection (inspecting contents of spaces, accessing server configuration).
+
+
+.. container:: table
+
+    **Complexity Factors that may affect data
+    manipulation functions in the box library**
+
+    +-------------------+-----------------------------------------------------+
+    | Index size        | The number of index keys is the same as the number  |
+    |                   | of tuples in the data set. For a TREE index, if     |
+    |                   | there are more keys then the lookup time will be    |
+    |                   | greater, although of course the effect is not       |
+    |                   | linear. For a HASH index, if there are more keys    |
+    |                   | then there is more RAM use, but the number of       |
+    |                   | low-level steps tends to remain constant.           |
+    +-------------------+-----------------------------------------------------+
+    | Index type        | Typically a HASH index is faster than a TREE index  |
+    |                   | if the number of tuples in the tuple set is greater |
+    |                   | than one.                                           |
+    +-------------------+-----------------------------------------------------+
+    | Number of indexes | Ordinarily only one index is accessed to retrieve   |
+    | accessed          | one tuple. But to update the tuple, there must be N |
+    |                   | accesses if the tuple set has N different indexes.  |
+    +-------------------+-----------------------------------------------------+
+    | Number of tuples  | A few requests, for example select, can retrieve    |
+    | accessed          | multiple tuples. This factor is usually less        |
+    |                   | important than the others.                          |
+    +-------------------+-----------------------------------------------------+
+    | WAL settings      | The important setting for the write-ahead log is    |
+    |                   | `wal_mode`_. If the setting causes no writing or    |
+    |                   | delayed writing, this factor is unimportant. If the |
+    |                   | settings causes every data-change request to wait   |
+    |                   | for writing to finish on a slow device, this factor |
+    |                   | is more important than all the others.              |
+    +-------------------+-----------------------------------------------------+
+
+.. _wal_mode: http://tarantool.org/doc/user_guide.html#wal_mode
+
+In the discussion of each data-manipulation function there will be a note about
+which Complexity Factors might affect the function's resource usage.
+
+=====================================================================
+            The two storage engines: memtx and sophia
+=====================================================================
+
+A storage engine is a set of very-low-level routines which actually store and
+retrieve tuple values. Tarantool offers a choice of two storage engines: memtx
+(the in-memory storage engine) and sophia (the on-disk storage engine).
+To specify that the engine should be sophia, add a clause: ``engine = 'sophia'``.
+The manual concentrates on memtx because it is the default and has been around
+longer. But sophia is a working key-value engine and will especially appeal to
+users who like to see data go directly to disk, so that recovery time might be
+shorter and database size might be larger. For architectural explanations and
+benchmarks, see sphia.org. On the other hand, sophia lacks some functions and
+options that are available with memtx. Where that is the case, the relevant
+description will contain the words "only applicable for the memtx storage engine".

doc/sphinx/reference/fiber-ipc.rst

@@ -30,7 +30,7 @@ other Lua object. Use object-oriented syntax, for example
     :return: new channel.
     :rtype:  userdata
 
-.. class:: channel
+.. class:: channel_object
 
     .. method:: put(message[, timeout])
 

doc/sphinx/reference/index.rst

 -------------------------------------------------------------------------------
-                              Library Reference
+                              Reference Manual
 -------------------------------------------------------------------------------
 
 Lua_ is a light-weight, multi-paradigm, embeddable language. Stored procedures
@@ -28,3 +28,4 @@ Lua functions can run in the background and perform administrative tasks.
     pickle
     other
     expirationd
+    box/index

doc/sphinx/reference/socket.rst

@@ -61,7 +61,7 @@ are ``errno``, ``error``.
     |    teardown    +-------------+
     |                | close       |
     +----------------+-------------+
-    |                | errno       |
+    |                | error       |
     | error checking +-------------+
     |                | errno       |
     +----------------+-------------+
@@ -149,13 +149,12 @@ the function invocations will look like ``sock:function_name(...)``.
 
         socket.tcp_server('localhost', 3302, function () end).
 
-
 .. class:: socket_object
 
     .. method:: sysconnect(host, port)
 
         Connect a socket to a remote host. The argument values are the same as
-        in the `Linux man page <http://man7.org/linux/man-pages/man2/connect.2.html>`_.
+        in the Linux man page [1]_.
         The host must be an IP address.
 
         Parameters:
@@ -181,6 +180,7 @@ the function invocations will look like ``sock:function_name(...)``.
             sock:sysconnect('127.0.0.1', 80)
 
     .. method:: send(data)
+                write(data)
 
         Send data over a connected socket.
 
@@ -188,11 +188,6 @@ the function invocations will look like ``sock:function_name(...)``.
         :return: true if success, false if error.
         :rtype:  boolean
 
-        .. NOTE::
-
-            The function ``sock:write(...)`` has
-            the same parameters and same effect.
-
     .. method:: syswrite(size)
 
         Write as much as possible data to the socket buffer if non-blocking.
@@ -243,7 +238,7 @@ the function invocations will look like ``sock:function_name(...)``.
     .. method:: bind(host [, port])
 
         Bind a socket to the given host/port. A UDP socket after binding
-        can be used to receive data (see :meth:`socket_object.recvfrom()`).
+        can be used to receive data (see :func:`socket_object.recvfrom`).
         A TCP socket can be used to accept new connections, after it has
         been put in listen mode.
 
@@ -264,7 +259,7 @@ the function invocations will look like ``sock:function_name(...)``.
                         may be ``SOMAXCONN``.
 
         :return: true for success, false for error.
-        :rtype:  boolean
+        :rtype: boolean.
 
     .. method:: accept()
 
@@ -340,7 +335,7 @@ the function invocations will look like ``sock:function_name(...)``.
     .. method:: setsockopt(level, name, value)
 
         Set socket flags. The argument values are the same as in the
-        `Linux man page <http://man7.org/linux/man-pages/man2/setsockopt.2.html>`_.
+        Linux man page [2]_.
         The ones that Tarantool accepts are:
 
             * SO_ACCEPTCONN
@@ -379,7 +374,7 @@ the function invocations will look like ``sock:function_name(...)``.
     .. method:: linger([active])
 
         Set or clear the SO_LINGER flag. For a description of the flag, see
-        `Linux man page <http://man7.org/linux/man-pages/man1/loginctl.1.html>`_.
+        Linux man page [3]_.
 
         :param boolean active:
 
@@ -514,3 +509,8 @@ computer to communicate with itself, but shows that the system works.
 
 
 .. _luasocket: https://github.com/diegonehab/luasocket
+
+.. [1] http://man7.org/linux/man-pages/man2/connect.2.html
+.. [2] http://man7.org/linux/man-pages/man2/setsockopt.2.html
+.. [3] http://man7.org/linux/man-pages/man1/loginctl.1.html
+