Merge branch '1.6' of https://github.com/tarantool/tarantool

doc/sphinx/book/box/box_index.rst

@@ -354,12 +354,16 @@ API is a direct binding to corresponding methods of index objects of type
         that the search will return tuples where the first value
         is greater than or equal to 'XY'. The conditional statement
         within the loop ensures that the looping will stop when the
-        first two letters are not 'XY'. |br|
-        :codenormal:`for _,tuple in box.space.t.index.primary:pairs("XY",{iterator = "GE"}) do` |br|
-        |nbsp| |nbsp| :codenormal:`if (string.sub(tuple[1], 1, 2) ~= "XY") then break end` |br|
-        |nbsp| |nbsp| :codenormal:`print(tuple)` |br|
-        |nbsp| |nbsp| :codenormal:`end` |br|
-
+        first two letters are not 'XY'.
+
+        .. code-block:: lua
+        
+            for tuple in
+            box.space.t.index.primary:pairs("XY",{iterator = "GE"}) do
+              if (string.sub(tuple[1], 1, 2) ~= "XY") then break end
+              print(tuple)
+            end
+    
         **Third Example of index pairs():**
 
         This Lua code finds all the tuples whose primary key values are
@@ -370,11 +374,15 @@ API is a direct binding to corresponding methods of index objects of type
         that the search will return tuples where the first value
         is greater than or equal to 1000. The conditional statement
         within the loop ensures that the looping will stop when the
-        first value is greater than 1999. |br|
-        :codenormal:`for _,tuple in box.space.t2.index.primary:pairs(1000,{iterator = "GE"}) do` |br|
-        |nbsp| |nbsp| :codenormal:`if (tuple[1] > 1999) then break end` |br|
-        |nbsp| |nbsp| :codenormal:`print(tuple)` |br|
-        |nbsp| |nbsp| :codenormal:`end` |br|
+        first value is greater than 1999.
+
+        .. code-block:: lua
+
+            for tuple in
+            box.space.t2.index.primary:pairs(1000,{iterator = "GE"}) do
+              if (tuple[1] > 1999) then break end
+              print(tuple)
+            end
 
     .. _index_object_select:
 
@@ -834,26 +842,30 @@ Lua functions `os.date()`_ and `string.sub()`_.
 =================================================================
 
 Here is an example that shows how to build one's own iterator.
-The paged_iter function is an "iterator function", which will only be
+The ``paged_iter`` function is an "iterator function", which will only be
 understood by programmers who have read the Lua
 manual section
 `Iterators and Closures <https://www.lua.org/pil/7.1.html>`_.
 It does paginated retrievals, that is, it returns 10
 tuples at a time from a table named "t", whose
-primary key was defined with :codenormal:`create_index('primary',{parts={1,'STR'}})`. |br|
-|nbsp| |nbsp| :codenormal:`function paged_iter(search_key, tuples_per_page)` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`local iterator_string = "GE"` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`return function ()` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`local page = box.space.t.index[0]:select(search_key,` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`{iterator = iterator_string, limit=tuples_per_page})` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`if #page == 0 then return nil end` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`search_key = page[#page][1]` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`iterator_string = "GT"` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`return page` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`end` |br|
-|nbsp| |nbsp| :codenormal:`end`
-
-Programmers who use paged_iter do not need to know
+primary key was defined with 
+:codenormal:`create_index('primary',{parts={1,'STR'}})`.
+
+.. code-block:: lua
+    
+    function paged_iter(search_key, tuples_per_page)
+      local iterator_string = "GE"
+      return function ()
+      local page = box.space.t.index[0]:select(search_key,
+        {iterator = iterator_string, limit=tuples_per_page})
+      if #page == 0 then return nil end
+      search_key = page[#page][1]
+      iterator_string = "GT"
+      return page
+      end
+    end
+    
+Programmers who use ``paged_iter`` do not need to know
 why it works, they only need to know that, if they
 call it within a loop, they will get 10 tuples
 at a time until there are no more tuples. In this
@@ -861,11 +873,14 @@ example the tuples are merely printed, a page at a time.
 But it should be simple to change the functionality,
 for example by yielding after each retrieval, or
 by breaking when the tuples fail to match some
-additional criteria. |br|
-|nbsp| |nbsp| :codenormal:`for page in paged_iter("X", 10) do` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`print("New Page. Number Of Tuples = " .. #page)` |br|
-|nbsp| |nbsp| |nbsp| |nbsp| :codenormal:`for i=1,#page,1 do print(page[i]) end` |br|
-|nbsp| |nbsp| :codenormal:`end`
+additional criteria.
+
+.. code-block:: lua
+
+    for page in paged_iter("X", 10) do
+      print("New Page. Number Of Tuples = " .. #page)
+      for i=1,#page,1 do print(page[i]) end
+    end
 
 .. _RTREE:
 

doc/sphinx/dev_guide/documentation_guidelines.rst

@@ -26,6 +26,41 @@ 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.
 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+              Formatting code snippets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For code snippets, we mainly use the ``code-block`` directive with an
+appropriate highlighting language. The most commonly used highlighting languages
+are:
+
+  * ``.. code-block:: tarantoolsession``
+  * ``.. code-block:: console``
+  * ``.. code-block:: lua``
+
+For example (a code snippet in Lua):
+
+.. code-block:: lua
+
+    for page in paged_iter("X", 10) do
+      print("New Page. Number Of Tuples = " .. #page)
+      for i=1,#page,1 do print(page[i]) end
+    end
+
+In rare cases, when we need custom highlight for specific parts of a code
+snippet and the ``code-block`` directive is not enough, we use the per-line
+``codenormal`` directive together with explicit output formatting (defined in 
+:file:`doc/sphinx/_static/sphinx_design.css`).
+
+For example (a tdb session with custom formatting in bold, blue and green):
+
+:codenormal:`$` :codebold:`tarantool example.lua` |br|
+:codeblue:`(TDB)` |nbsp| :codegreen:`Tarantool debugger v.0.0.3. Type h for help` |br|
+:codenormal:`example.lua` |br|
+:codeblue:`(TDB)` |nbsp| :codegreen:`[example.lua]` |br|
+:codeblue:`(TDB)` |nbsp| :codenormal:`3: i = 1` |br|
+:codeblue:`(TDB)>` |br|
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
               Making comments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~