From 3d788298d1a8298a419948efb6a0a68195b9bc10 Mon Sep 17 00:00:00 2001
From: lenkis <elena.shebunyaeva@gmail.com>
Date: Thu, 30 Jun 2016 14:37:36 +0300
Subject: [PATCH] Added a new subsection "Formatting code snippets"
---
.../dev_guide/documentation_guidelines.rst | 35 +++++++++++++++++++
1 file changed, 35 insertions(+)
diff --git a/doc/sphinx/dev_guide/documentation_guidelines.rst b/doc/sphinx/dev_guide/documentation_guidelines.rst
index dabd527576..efeb2d2a86 100644
--- a/doc/sphinx/dev_guide/documentation_guidelines.rst
+++ b/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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
GitLab