Merge "Enhance code samples chapter"

doc/doc-contrib-guide/source/rst-conv/inline-markups.rst

@@ -21,7 +21,9 @@ To insert a semantic markup into your document, use the syntax below.
 
 .. code-block:: rst
 
-  :markup:`inline text`
+   :markup:`inline text`
+
+.. end
 
 Application
 ~~~~~~~~~~~

doc/doc-contrib-guide/source/rst-conv/rst2bash.rst

@@ -53,7 +53,7 @@ syntax format.
 
   * Example 2: Configure a configuration file.
 
-    .. code-block:: none
+    .. code-block:: rst
 
       .. path /etc/keystone/keystone.conf
       .. code-block:: ini
@@ -68,7 +68,7 @@ syntax format.
 
 * The ``only`` tags should be closed with ``endonly``.
 
-  .. code-block:: none
+  .. code-block:: rst
 
     .. only:: ubuntu or debian
 

doc/doc-contrib-guide/source/rst-conv/source-code.rst

@@ -79,7 +79,7 @@ files, ``console`` for console inputs and outputs, and so on.
 
 **Input**
 
-.. code-block:: none
+.. code-block:: rst
 
    .. path /path/to/config/file
    .. code-block:: ini
@@ -92,6 +92,8 @@ files, ``console`` for console inputs and outputs, and so on.
 
    .. end
 
+.. end
+
 **Output**
 
 .. code-block:: ini
@@ -102,6 +104,8 @@ files, ``console`` for console inputs and outputs, and so on.
    [DEFAULT]
    # List of directories to load filter definitions from (separated by ',').
 
+.. end
+
 .. note::
 
    When you write the command example, you should write the input and output
@@ -109,6 +113,46 @@ files, ``console`` for console inputs and outputs, and so on.
    not split them into input block and output block.
    You can omit the output where appropriate.
 
+Options of code-block directive
+-------------------------------
+
+You can add line numbers to code examples with the ``:linenos:`` parameter and
+highlight some specific lines with the ``:emphasize-lines:`` parameter:
+
+**Input**
+
+.. code-block:: rst
+
+   .. code-block:: python
+      :linenos:
+      :emphasize-lines: 3,5-6
+
+      def some_function():
+          interesting = False
+          print 'This line is highlighted.'
+          print 'This one is not...'
+          print '...but this one is.'
+          print 'This one is highlighted too.'
+
+   .. end
+
+.. end
+
+**Output**
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 3,5-6
+
+   def some_function():
+       interesting = False
+       print 'This line is highlighted.'
+       print 'This one is not...'
+       print '...but this one is.'
+       print 'This one is highlighted too.'
+
+.. end
+
 .. _remote-block:
 
 Literal block using a remote file
@@ -133,7 +177,7 @@ content from a remote URL (``http`` or ``https``).
 
 **Input**
 
-.. code-block:: none
+.. code-block:: rst
 
    .. path /path/to/config/file
    .. remote-code-block:: ini