rst highlighting and better explanation of skip (#170)

Author: felix-hilden

docs/src/examples.rst

@@ -45,7 +45,9 @@ particularly in the reference documentation itself:
 
 .. autolink-examples:: lib.Knight
 
-Such a table is generated with :rst:dir:`autolink-examples`::
+Such a table is generated with :rst:dir:`autolink-examples`:
+
+.. code-block:: rst
 
    .. autolink-examples:: lib.Knight
 
@@ -60,14 +62,18 @@ The import can be hidden instead.
 
   lib.Knight().taunt()
 
-The previous block is produced with :rst:dir:`autolink-preface`::
+The previous block is produced with :rst:dir:`autolink-preface`:
+
+.. code-block:: rst
 
    .. autolink-preface:: import lib
    .. code:: python
 
         lib.Knight().taunt()
 
-A multiline preface can be written in the content portion of the directive::
+A multiline preface can be written in the content portion of the directive:
+
+.. code-block:: rst
 
    .. autolink-preface::
 
@@ -96,7 +102,9 @@ the previous left off.
        print(knight.taunt())
        knight.scratch()
 
-This was achieved with :rst:dir:`autolink-concat`::
+This was achieved with :rst:dir:`autolink-concat`:
+
+.. code-block:: rst
 
    .. autolink-concat:: section
    .. code:: python
@@ -124,7 +132,9 @@ and preventing it from being included in further sources with concatenation.
    import lib
    lib.Knight()
 
-Which is done via :rst:dir:`autolink-skip`::
+Which is done via :rst:dir:`autolink-skip`:
+
+.. code-block:: rst
 
    .. autolink-skip::
    .. code:: python
@@ -196,7 +206,9 @@ Reference tables across intersphinx work too:
 It seems that the reference type information is more important
 for Sphinx when dealing with external modules,
 likely because the references cannot be resolved dynamically.
-Please specify a ``type`` in :rst:dir:`autolink-examples`::
+Please specify a ``type`` in :rst:dir:`autolink-examples`:
+
+.. code-block:: rst
 
    .. autolink-examples:: numpy.linspace
       :type: func

docs/src/reference.rst

@@ -128,7 +128,7 @@ Directives
    Skip sphinx-codeautolink functionality.
    ``level``, if specified, must be one of:
 
-   - "next" - next block (default)
+   - "next" - next encountered block (default)
    - "section" - blocks until the next title
    - "file" - all blocks in the current file
    - "off" - turn skipping off
@@ -137,6 +137,9 @@ Directives
    it is not processed (e.g. non-Python blocks) to avoid placement confusion.
    Skipped blocks are ignored in block concatenation as well, and concatenation
    is resumed without breaks after skipping is over.
+   "Next" doesn't need to be specified right before the block that would consume
+   it. For e.g. literal blocks the skip directive would be inserted before the
+   preceding paragraph.
 
 CSS class
 ---------