Fix many ReST issues in the docs.

10 files changed, 85 insertions, 46 deletions

diff --git a/docs/src/quickstart/build.rst b/docs/src/quickstart/build.rst
index 0da55750f..5382bc663 100644
--- a/docs/src/quickstart/build.rst
+++ b/docs/src/quickstart/build.rst
@@ -63,7 +63,7 @@ Cython can be used conveniently and interactively from a web browser
 through the Jupyter notebook.  To install Jupyter notebook, e.g. into a virtualenv,
 use pip:
 
-.. sourcecode:: bash
+.. code-block:: bash
 
     (venv)$ pip install jupyter
     (venv)$ jupyter notebook
diff --git a/docs/src/tutorial/clibraries.rst b/docs/src/tutorial/clibraries.rst
index 08c491d36..514d345c3 100644
--- a/docs/src/tutorial/clibraries.rst
+++ b/docs/src/tutorial/clibraries.rst
@@ -223,11 +223,15 @@ The ``sources`` compiler directive gives the path of the C
 files that setuptools is going to compile and
 link (statically) into the resulting extension module.
 In general all relevant header files should be found in ``include_dirs``.
-Now we can build the project using::
+Now we can build the project using:
+
+.. code-block:: bash
 
     $ python setup.py build_ext -i
 
-And test whether our build was successful::
+And test whether our build was successful:
+
+.. code-block:: bash
 
     $ python -c 'import queue; Q = queue.Queue()'
 
@@ -239,14 +243,18 @@ Dynamic linking is useful, if the library we are going to wrap is already
 installed on the system. To perform dynamic linking we first need to
 build and install c-alg.
 
-To build c-algorithms on your system::
+To build c-algorithms on your system:
+
+.. code-block:: bash
 
     $ cd c-algorithms
     $ sh autogen.sh
     $ ./configure
     $ make
 
-to install CAlg run::
+to install CAlg run:
+
+.. code-block:: bash
 
     $ make install
 
@@ -274,13 +282,17 @@ to
                   libraries=["calg"])
         ])
 
-Now we should be able to build the project using::
+Now we should be able to build the project using:
+
+.. code-block:: bash
 
     $ python setup.py build_ext -i
 
 If the `libcalg` is not installed in a 'normal' location, users can provide the
 required parameters externally by passing appropriate C compiler
-flags, such as::
+flags, such as:
+
+.. code-block:: bash
 
     CFLAGS="-I/usr/local/otherdir/calg/include"  \
     LDFLAGS="-L/usr/local/otherdir/calg/lib"     \
@@ -289,12 +301,16 @@ flags, such as::
 
 
 Before we run the module, we also need to make sure that `libcalg` is in
-the `LD_LIBRARY_PATH` environment variable, e.g. by setting::
+the `LD_LIBRARY_PATH` environment variable, e.g. by setting:
+
+.. code-block:: bash
 
    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
 
 Once we have compiled the module for the first time, we can now import
-it and instantiate a new Queue::
+it and instantiate a new Queue:
+
+.. code-block:: bash
 
     $ export PYTHONPATH=.
     $ python -c 'import queue; Q = queue.Queue()'
diff --git a/docs/src/tutorial/cython_tutorial.rst b/docs/src/tutorial/cython_tutorial.rst
index c4cb64101..d4ff38909 100644
--- a/docs/src/tutorial/cython_tutorial.rst
+++ b/docs/src/tutorial/cython_tutorial.rst
@@ -49,7 +49,7 @@ see :ref:`compilation`). Your :file:`setup.py` should look like::
 
 To use this to build your Cython file use the commandline options:
 
-.. sourcecode:: text
+.. code-block:: text
 
     $ python setup.py build_ext --inplace
 
@@ -109,7 +109,7 @@ module name, doing this we have:
 
 Build the extension with the same command used for the helloworld.pyx:
 
-.. sourcecode:: text
+.. code-block:: text
 
     $ python setup.py build_ext --inplace
 
diff --git a/docs/src/tutorial/numpy.rst b/docs/src/tutorial/numpy.rst
index 5fa205976..a4efb0f65 100644
--- a/docs/src/tutorial/numpy.rst
+++ b/docs/src/tutorial/numpy.rst
@@ -28,7 +28,7 @@ systems, it will be :file:`yourmod.pyd`). We
 run a Python session to test both the Python version (imported from
 ``.py``-file) and the compiled Cython module.
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [1]: import numpy as np
     In [2]: import convolve_py
@@ -69,7 +69,7 @@ compatibility. Consider this code (*read the comments!*) :
 
 After building this and continuing my (very informal) benchmarks, I get:
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [21]: import convolve2
     In [22]: %timeit -n2 -r3 convolve2.naive_convolve(f, g)
@@ -97,7 +97,7 @@ These are the needed changes::
 
 Usage:
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [18]: import convolve3
     In [19]: %timeit -n3 -r100 convolve3.naive_convolve(f, g)
@@ -143,7 +143,7 @@ if we try to actually use negative indices with this disabled.
 The function call overhead now starts to play a role, so we compare the latter
 two examples with larger N:
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [11]: %timeit -n3 -r100 convolve4.naive_convolve(f, g)
     3 loops, best of 100: 5.97 ms per loop
diff --git a/docs/src/tutorial/pxd_files.rst b/docs/src/tutorial/pxd_files.rst
index 75fc7b1af..0a22f7a2a 100644
--- a/docs/src/tutorial/pxd_files.rst
+++ b/docs/src/tutorial/pxd_files.rst
@@ -50,7 +50,9 @@ namespaces, similar to ``__init__.py`` files in Python.
 Continuing the integration example, we could package the module as follows:
 
 1.  Place the module files in a directory tree as one usually would for
-    Python::
+    Python:
+
+    .. code-block:: text
 
         CyIntegration/
         ├── __init__.pyx
diff --git a/docs/src/userguide/extension_types.rst b/docs/src/userguide/extension_types.rst
index e7f95a7ab..7bb621fcc 100644
--- a/docs/src/userguide/extension_types.rst
+++ b/docs/src/userguide/extension_types.rst
@@ -314,7 +314,7 @@ when it is deleted.::
     del shop.cheese
     print(shop.cheese)
 
-.. sourcecode:: text
+.. code-block:: text
 
     # Test output
     We don't have: []
@@ -402,7 +402,7 @@ compared to a :keyword:`cdef` method::
     print("p2:")
     p2.describe()
 
-.. sourcecode:: text
+.. code-block:: text
 
     # Output
     p1:
@@ -824,7 +824,7 @@ built-in complex object.::
        because, in the Python header files, the ``PyComplexObject`` struct is
        declared with:
 
-       .. sourcecode:: c
+       .. code-block:: c
 
         typedef struct {
             ...
@@ -909,7 +909,9 @@ For example, we may have an extension module ``foo_extension``::
             self.field1 = f1
             self.field2 = f2
 
-but a C struct in a file ``foo_nominal.h``::
+but a C struct in a file ``foo_nominal.h``:
+
+.. code-block:: c
 
    typedef struct {
         PyObject_HEAD
diff --git a/docs/src/userguide/external_C_code.rst b/docs/src/userguide/external_C_code.rst
index 4b8ddd8a0..1afbe2a18 100644
--- a/docs/src/userguide/external_C_code.rst
+++ b/docs/src/userguide/external_C_code.rst
@@ -189,19 +189,19 @@ same applies equally to union and enum declarations.
 +-------------------------+---------------------------------------------+-----------------------------------------------------------------------+
 | C code                  | Possibilities for corresponding Cython Code | Comments                                                              |
 +=========================+=============================================+=======================================================================+
-| .. sourcecode:: c       | ::                                          | Cython will refer to the as ``struct Foo`` in the generated C code.   |
+| .. code-block:: c       | ::                                          | Cython will refer to the as ``struct Foo`` in the generated C code.   |
 |                         |                                             |                                                                       |
 |   struct Foo {          |   cdef struct Foo:                          |                                                                       |
 |     ...                 |     ...                                     |                                                                       |
 |   };                    |                                             |                                                                       |
 +-------------------------+---------------------------------------------+-----------------------------------------------------------------------+
-| .. sourcecode:: c       | ::                                          | Cython will refer to the type simply as ``Foo`` in                    |
+| .. code-block:: c       | ::                                          | Cython will refer to the type simply as ``Foo`` in                    |
 |                         |                                             | the generated C code.                                                 |
 |   typedef struct {      |   ctypedef struct Foo:                      |                                                                       |
 |     ...                 |     ...                                     |                                                                       |
 |   } Foo;                |                                             |                                                                       |
 +-------------------------+---------------------------------------------+-----------------------------------------------------------------------+
-| .. sourcecode:: c       | ::                                          | If the C header uses both a tag and a typedef with *different*        |
+| .. code-block:: c       | ::                                          | If the C header uses both a tag and a typedef with *different*        |
 |                         |                                             | names, you can use either form of declaration in Cython               |
 |   typedef struct foo {  |   cdef struct foo:                          | (although if you need to forward reference the type,                  |
 |     ...                 |     ...                                     | you'll have to use the first form).                                   |
@@ -212,7 +212,7 @@ same applies equally to union and enum declarations.
 |                         |   ctypedef struct Foo:                      |                                                                       |
 |                         |     ...                                     |                                                                       |
 +-------------------------+---------------------------------------------+-----------------------------------------------------------------------+
-| .. sourcecode:: c       | ::                                          | If the header uses the *same* name for the tag and typedef, you       |
+| .. code-block:: c       | ::                                          | If the header uses the *same* name for the tag and typedef, you       |
 |                         |                                             | won't be able to include a :keyword:`ctypedef` for it -- but then,    |
 |   typedef struct Foo {  |   cdef struct Foo:                          | it's not necessary.                                                   |
 |     ...                 |     ...                                     |                                                                       |
diff --git a/docs/src/userguide/numpy_tutorial.rst b/docs/src/userguide/numpy_tutorial.rst
index f34b2a0da..a51eedaf8 100644
--- a/docs/src/userguide/numpy_tutorial.rst
+++ b/docs/src/userguide/numpy_tutorial.rst
@@ -88,7 +88,9 @@ However there are several options to automate these steps:
 Installation
 =============
 
-If you already have a C compiler, just do::
+If you already have a C compiler, just do:
+
+.. code-block:: bash
 
    pip install Cython
 
@@ -97,7 +99,9 @@ otherwise, see :ref:`the installation page <install>`.
 
 As of this writing SAGE comes with an older release of Cython than required
 for this tutorial. So if using SAGE you should download the newest Cython and
-then execute ::
+then execute :
+
+.. code-block:: bash
 
     $ cd path/to/cython-distro
     $ path-to-sage/sage -python setup.py install
@@ -108,7 +112,9 @@ Manual compilation
 ====================
 
 As it is always important to know what is going on, I'll describe the manual
-method here. First Cython is run::
+method here. First Cython is run:
+
+.. code-block:: bash
 
     $ cython yourmod.pyx
 
@@ -120,7 +126,9 @@ line by line.
 Then we compile the C file. This may vary according to your system, but the C
 file should be built like Python was built. Python documentation for writing
 extensions should have some details. On Linux this often means something
-like::
+like:
+
+.. code-block:: bash
 
     $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing -I/usr/include/python2.7 -o yourmod.so yourmod.c
 
@@ -166,7 +174,7 @@ This should be compiled to produce :file:`compute_cy.so` for Linux systems
 run a Python session to test both the Python version (imported from
 ``.py``-file) and the compiled Cython module.
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [1]: import numpy as np
     In [2]: array_1 = np.random.uniform(0, 1000, size=(3000, 2000)).astype(np.intc)
@@ -218,7 +226,7 @@ of C code to set up while in :file:`compute_typed.c` a normal C for loop is used
 
 After building this and continuing my (very informal) benchmarks, I get:
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [13]: %timeit compute_typed.compute(array_1, array_2, a, b, c)
     26.5 s ± 422 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
@@ -287,7 +295,7 @@ Here is how to use them in our code:
 
 Let's see how much faster accessing is now.
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [22]: %timeit compute_memview.compute(array_1, array_2, a, b, c)
     22.9 ms ± 197 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)
@@ -326,7 +334,7 @@ mode in many ways, see :ref:`compiler-directives` for more
 information.
 
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [23]: %timeit compute_index.compute(array_1, array_2, a, b, c)
     16.8 ms ± 25.4 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
@@ -376,7 +384,7 @@ all about, you can see `this answer on StackOverflow
 For the sake of giving numbers, here are the speed gains that you should
 get by declaring the memoryviews as contiguous:
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [23]: %timeit compute_contiguous.compute(array_1, array_2, a, b, c)
     11.1 ms ± 30.2 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
@@ -405,7 +413,7 @@ be useful when using fused types.
 
 We now do a speed test:
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [24]: %timeit compute_infer_types.compute(array_1, array_2, a, b, c)
     11.5 ms ± 261 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
@@ -439,14 +447,14 @@ In this case, our function now works for ints, doubles and floats.
 
 We can check that the output type is the right one::
 
-    >>>compute(array_1, array_2, a, b, c).dtype
+    >>> compute(array_1, array_2, a, b, c).dtype
     dtype('int32')
-    >>>compute(array_1.astype(np.double), array_2.astype(np.double), a, b, c).dtype
+    >>> compute(array_1.astype(np.double), array_2.astype(np.double), a, b, c).dtype
     dtype('float64')
 
 We now do a speed test:
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [25]: %timeit compute_fused_types.compute(array_1, array_2, a, b, c)
     11.5 ms ± 258 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
@@ -463,7 +471,9 @@ like the function :func:`prange`. You can see more information about Cython and
 parallelism in :ref:`parallel`. Since we do elementwise operations, we can easily
 distribute the work among multiple threads. It's important not to forget to pass the
 correct arguments to the compiler to enable OpenMP. When using the Jupyter notebook,
-you should use the cell magic like this::
+you should use the cell magic like this:
+
+.. code-block:: ipython
 
     %%cython --force
     # distutils: extra_compile_args=-fopenmp
@@ -476,7 +486,7 @@ declare our :func:`clip` function ``nogil``.
 
 We can have substantial speed gains for minimal effort:
 
-.. sourcecode:: ipython
+.. code-block:: ipythonconsole
 
     In [25]: %timeit compute_prange.compute(array_1, array_2, a, b, c)
     9.33 ms ± 412 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
diff --git a/docs/src/userguide/source_files_and_compilation.rst b/docs/src/userguide/source_files_and_compilation.rst
index bc3b08677..7c8d0522d 100644
--- a/docs/src/userguide/source_files_and_compilation.rst
+++ b/docs/src/userguide/source_files_and_compilation.rst
@@ -44,7 +44,7 @@ Compiling with the ``cython`` command
 One way is to compile it manually with the Cython
 compiler, e.g.:
 
-.. sourcecode:: text
+.. code-block:: text
 
     $ cython primes.pyx
 
@@ -62,7 +62,9 @@ Compiling with the ``cythonize`` command
 ----------------------------------------
 
 Run the ``cythonize`` compiler command with your options and list of
-``.pyx`` files to generate an extension module.  For example::
+``.pyx`` files to generate an extension module.  For example:
+
+.. code-block:: bash
 
     $ cythonize -a -i yourmod.pyx
 
@@ -82,7 +84,9 @@ There simpler command line tool ``cython`` only invokes the source code translat
 In the case of manual compilation, how to compile your ``.c`` files will vary
 depending on your operating system and compiler.  The Python documentation for
 writing extension modules should have some details for your system.  On a Linux
-system, for example, it might look similar to this::
+system, for example, it might look similar to this:
+
+.. code-block:: bash
 
     $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing \
           -I/usr/include/python3.5 -o yourmod.so yourmod.c
@@ -121,7 +125,10 @@ If your build depends directly on Cython in this way,
 then you may also want to inform pip that :mod:`Cython` is required for
 :file:`setup.py` to execute, following `PEP 518
 <https://www.python.org/dev/peps/pep-0518/>`, creating a :file:`pyproject.toml`
-file containing, at least::
+file containing, at least:
+
+.. code-block:: ini
+
 
     [build-system]
     requires = ["setuptools", "wheel", "Cython"]
@@ -129,7 +136,7 @@ file containing, at least::
 To understand the :file:`setup.py` more fully look at the official `setuptools
 documentation`_. To compile the extension for use in the current directory use:
 
-.. sourcecode:: text
+.. code-block:: text
 
     $ python setup.py build_ext --inplace
 
@@ -975,7 +982,9 @@ One can set compiler directives through a special header comment near the top of
 The comment must appear before any code (but can appear after other
 comments or whitespace).
 
-One can also pass a directive on the command line by using the -X switch::
+One can also pass a directive on the command line by using the -X switch:
+
+.. code-block:: bash
 
     $ cython -X boundscheck=True ...
 
diff --git a/docs/src/userguide/wrapping_CPlusPlus.rst b/docs/src/userguide/wrapping_CPlusPlus.rst
index 1d8a25835..cdcb2215b 100644
--- a/docs/src/userguide/wrapping_CPlusPlus.rst
+++ b/docs/src/userguide/wrapping_CPlusPlus.rst
@@ -462,7 +462,7 @@ Static member method
 
 If the Rectangle class has a static member:
 
-.. sourcecode:: c++
+.. code-block:: c++
 
     namespace shapes {
         class Rectangle {