9 files changed, 126 insertions, 60 deletions
diff --git a/docs/src/quickstart/build.rst b/docs/src/quickstart/build.rst
index 628ed2604..3cbcfa087 100644
--- a/docs/src/quickstart/build.rst
+++ b/docs/src/quickstart/build.rst
@@ -3,23 +3,27 @@ Building Cython code
 
 Cython code must, unlike Python, be compiled. This happens in two stages:
 
- - A ``.pyx`` file is compiled by Cython to a ``.c`` file, containing
+ - A ``.pyx`` or ``.py`` file is compiled by Cython to a ``.c`` file, containing
    the code of a Python extension module.
  - The ``.c`` file is compiled by a C compiler to
    a ``.so`` file (or ``.pyd`` on Windows) which can be
    ``import``-ed directly into a Python session.
-   Distutils or setuptools take care of this part.
+   `setuptools <https://setuptools.readthedocs.io/>`_ takes care of this part.
    Although Cython can call them for you in certain cases.
-
-To understand fully the Cython + distutils/setuptools build process,
+   
+To understand fully the Cython + setuptools build process,
 one may want to read more about
 `distributing Python modules <https://docs.python.org/3/distributing/index.html>`_.
 
 There are several ways to build Cython code:
 
- - Write a distutils/setuptools ``setup.py``. This is the normal and recommended way.
+ - Write a setuptools ``setup.py``. This is the normal and recommended way.
+ - Run the ``cythonize`` command-line utility. This is a good approach for
+   compiling a single Cython source file directly to an extension.
+   A source file can be built "in place" (so that the extension module is created
+   next to the source file, ready to be imported) with ``cythonize -i filename.pyx``.
  - Use :ref:`Pyximport<pyximport>`, importing Cython ``.pyx`` files as if they
-   were ``.py`` files (using distutils to compile and build in the background).
+   were ``.py`` files (using setuptools to compile and build in the background).
    This method is easier than writing a ``setup.py``, but is not very flexible.
    So you'll need to write a ``setup.py`` if, for example, you need certain compilations options.
  - Run the ``cython`` command-line utility manually to produce the ``.c`` file
@@ -30,12 +34,12 @@ There are several ways to build Cython code:
    both of which allow Cython code inline.
    This is the easiest way to get started writing Cython code and running it.
 
-Currently, using distutils or setuptools is the most common way Cython files are built and distributed.
+Currently, using setuptools is the most common way Cython files are built and distributed.
 The other methods are described in more detail in the :ref:`compilation` section of the reference manual.
 
 
-Building a Cython module using distutils
-----------------------------------------
+Building a Cython module using setuptools
+-----------------------------------------
 
 Imagine a simple "hello world" script in a file ``hello.pyx``:
 
@@ -49,11 +53,10 @@ To build, run ``python setup.py build_ext --inplace``.  Then simply
 start a Python session and do ``from hello import say_hello_to`` and
 use the imported function as you see fit.
 
-One caveat if you use setuptools instead of distutils, the default
-action when running ``python setup.py install`` is to create a zipped
-``egg`` file which will not work with ``cimport`` for ``pxd`` files
-when you try to use them from a dependent package.
-To prevent this, include ``zip_safe=False`` in the arguments to ``setup()``.
+One caveat: the default action when running ``python setup.py install`` is to
+create a zipped ``egg`` file which will not work with ``cimport`` for ``pxd``
+files when you try to use them from a dependent package.  To prevent this,
+include ``zip_safe=False`` in the arguments to ``setup()``.
 
 .. _jupyter-notebook:
 
@@ -64,7 +67,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
@@ -74,14 +77,32 @@ and load the ``Cython`` extension from within the Jupyter notebook::
 
     %load_ext Cython
 
-Then, prefix a cell with the ``%%cython`` marker to compile it::
+Then, prefix a cell with the ``%%cython`` marker to compile it
+
+.. tabs::
+
+    .. group-tab:: Pure Python
+
+        .. code-block:: python
+
+            %%cython
+
+            a: cython.int = 0
+            for i in range(10):
+                a += i
+            print(a)
+
+
+    .. group-tab:: Cython
+
+        .. code-block:: python
 
-    %%cython
+            %%cython
 
-    cdef int a = 0
-    for i in range(10):
-        a += i
-    print(a)
+            cdef int a = 0
+            for i in range(10):
+                a += i
+            print(a)
 
 You can show Cython's code analysis by passing the ``--annotate`` option::
 
@@ -104,5 +125,6 @@ Using the Sage notebook
   functions defined in a Cython cell imported into the running session.
 
 
-.. [Jupyter] http://jupyter.org/
-.. [Sage] W. Stein et al., Sage Mathematics Software, http://www.sagemath.org/
+.. [Jupyter] https://jupyter.org/
+..
+   [Sage] W. Stein et al., Sage Mathematics Software, https://www.sagemath.org/
diff --git a/docs/src/quickstart/cythonize.rst b/docs/src/quickstart/cythonize.rst
index 22cad0470..d4895e10d 100644
--- a/docs/src/quickstart/cythonize.rst
+++ b/docs/src/quickstart/cythonize.rst
@@ -1,6 +1,9 @@
 Faster code via static typing
 =============================
 
+.. include::
+    ../two-syntax-variants-used
+
 Cython is a Python compiler.  This means that it can compile normal
 Python code without changes (with a few obvious exceptions of some as-yet
 unsupported language features, see :ref:`Cython limitations<cython-limitations>`).
@@ -33,6 +36,7 @@ Typing Variables
 Consider the following pure Python code:
 
 .. literalinclude:: ../../examples/quickstart/cythonize/integrate.py
+    :caption: integrate.py
 
 Simply compiling this in Cython merely gives a 35% speedup.  This is
 better than nothing, but adding some static types can make a much larger
@@ -40,7 +44,17 @@ difference.
 
 With additional type declarations, this might look like:
 
-.. literalinclude:: ../../examples/quickstart/cythonize/integrate_cy.pyx
+.. tabs::
+
+    .. group-tab:: Pure Python
+
+        .. literalinclude:: ../../examples/quickstart/cythonize/integrate_cy.py
+            :caption: integrate_cy.py
+
+    .. group-tab:: Cython
+
+        .. literalinclude:: ../../examples/quickstart/cythonize/integrate_cy.pyx
+            :caption: integrate_cy.pyx
 
 Since the iterator variable ``i`` is typed with C semantics, the for-loop will be compiled
 to pure C code.  Typing ``a``, ``s`` and ``dx`` is important as they are involved
@@ -55,27 +69,40 @@ Typing Functions
 
 Python function calls can be expensive -- in Cython doubly so because
 one might need to convert to and from Python objects to do the call.
-In our example above, the argument is assumed to be a C double both inside f()
+In our example above, the argument is assumed to be a C double both inside ``f()``
 and in the call to it, yet a Python ``float`` object must be constructed around the
 argument in order to pass it.
 
-Therefore Cython provides a syntax for declaring a C-style function,
-the cdef keyword:
+Therefore, Cython provides a way for declaring a C-style function,
+the Cython specific ``cdef`` statement, as well as the ``@cfunc`` decorator to
+declare C-style functions in Python syntax.  Both approaches are
+equivalent and produce the same C code:
+
+.. tabs::
+
+    .. group-tab:: Pure Python
+
+        .. literalinclude:: ../../examples/quickstart/cythonize/cdef_keyword.py
 
-.. literalinclude:: ../../examples/quickstart/cythonize/cdef_keyword.pyx
+    .. group-tab:: Cython
+
+        .. literalinclude:: ../../examples/quickstart/cythonize/cdef_keyword.pyx
 
 Some form of except-modifier should usually be added, otherwise Cython
 will not be able to propagate exceptions raised in the function (or a
 function it calls). The ``except? -2`` means that an error will be checked
 for if ``-2`` is returned (though the ``?`` indicates that ``-2`` may also
-be used as a valid return value).
+be used as a valid return value). The same can be expressed using only Python
+syntax with the decorator ``@exceptval(-2, check=True)``.
+
 Alternatively, the slower ``except *`` is always
 safe. An except clause can be left out if the function returns a Python
 object or if it is guaranteed that an exception will not be raised
-within the function call.
+within the function call.  Again, Cython provides the decorator ``@exceptval(check=True)``
+providing the same functionality.
 
-A side-effect of cdef is that the function is no longer available from
-Python-space, as Python wouldn't know how to call it. It is also no
+A side-effect of ``cdef`` (and the ``@cfunc`` decorator) is that the function is no longer
+visible from Python-space, as Python wouldn't know how to call it.  It is also no
 longer possible to change :func:`f` at runtime.
 
 Using the ``cpdef`` keyword instead of ``cdef``, a Python wrapper is also
@@ -84,7 +111,8 @@ typed values directly) and from Python (wrapping values in Python
 objects). In fact, ``cpdef`` does not just provide a Python wrapper, it also
 installs logic to allow the method to be overridden by python methods, even
 when called from within cython. This does add a tiny overhead compared to ``cdef``
-methods.
+methods.  Again, Cython provides a ``@ccall`` decorator which provides the same
+functionality as ``cpdef`` keyword.
 
 Speedup: 150 times over pure Python.
 
@@ -115,10 +143,20 @@ Lines that translate to C code have a plus (``+``) in front
 and can be clicked to show the generated code.
 
 This report is invaluable when optimizing a function for speed,
-and for determining when to :ref:`release the GIL <nogil>`:
+and for determining when it is possible to :ref:`release the GIL <nogil>`
+(be aware that releasing the GIL is only useful under limited
+circumstances, see :ref:`cython_and_gil` for more details):
 in general, a ``nogil`` block may contain only "white" code.
 
-.. figure:: htmlreport.png
+.. tabs::
+
+    .. group-tab:: Pure Python
+
+        .. figure:: htmlreport_py.png
+
+    .. group-tab:: Cython
+
+        .. figure:: htmlreport_pyx.png
 
 Note that Cython deduces the type of local variables based on their assignments
 (including as loop variable targets) which can also cut down on the need to
@@ -135,4 +173,3 @@ with this language feature. It can be of great help to cut down on the need to t
 everything, but it also can lead to surprises. Especially if one isn't familiar with
 arithmetic expressions with c types. A quick overview of those
 can be found `here <https://www.eskimo.com/~scs/cclass/int/sx4cb.html>`_.
-
diff --git a/docs/src/quickstart/demo.pyx b/docs/src/quickstart/demo.pyx
index 8c25f8992..a475dd03c 100644
--- a/docs/src/quickstart/demo.pyx
+++ b/docs/src/quickstart/demo.pyx
@@ -12,6 +12,7 @@ def timeit(f, label):
         first_time = elapsed
     print label, elapsed, (100*elapsed/first_time), '% or', first_time/elapsed, 'x'
 
+
 # Pure Python
 
 py_funcs = {'sin': sin}
@@ -30,22 +31,22 @@ def integrate_f(a, b, N):
 """ in py_funcs
 timeit(py_funcs['integrate_f'], "Python")
 
+
 # Just compiled
 
 def f0(x):
-      return x**2-x
+    return x**2-x
 
 def integrate_f0(a, b, N):
-      s = 0
-      dx = (b-a)/N
-      for i in range(N):
-          s += f0(a+i*dx)
-      return s * dx
+    s = 0
+    dx = (b-a)/N
+    for i in range(N):
+        s += f0(a+i*dx)
+    return s * dx
 
 timeit(integrate_f0, "Cython")
 
 
-
 # Typed vars
 
 def f1(double x):
@@ -63,7 +64,6 @@ def integrate_f1(double a, double b, int N):
 timeit(integrate_f1, "Typed vars")
 
 
-
 # Typed func
 
 cdef double f2(double x) except? -2:
diff --git a/docs/src/quickstart/htmlreport.png b/docs/src/quickstart/htmlreport.png
deleted file mode 100644
index cc30cec9f..000000000
--- a/docs/src/quickstart/htmlreport.png
+++ /dev/null
diff --git a/docs/src/quickstart/htmlreport_py.png b/docs/src/quickstart/htmlreport_py.png
new file mode 100755
index 000000000..a42a9d1cc
--- /dev/null
+++ b/docs/src/quickstart/htmlreport_py.png
diff --git a/docs/src/quickstart/htmlreport_pyx.png b/docs/src/quickstart/htmlreport_pyx.png
new file mode 100755
index 000000000..bc9cff2f9
--- /dev/null
+++ b/docs/src/quickstart/htmlreport_pyx.png
diff --git a/docs/src/quickstart/install.rst b/docs/src/quickstart/install.rst
index a71adffb5..979d0f178 100644
--- a/docs/src/quickstart/install.rst
+++ b/docs/src/quickstart/install.rst
@@ -7,9 +7,7 @@ Many scientific Python distributions, such as Anaconda [Anaconda]_,
 Enthought Canopy [Canopy]_, and Sage [Sage]_,
 bundle Cython and no setup is needed.  Note however that if your
 distribution ships a version of Cython which is too old you can still
-use the instructions below to update Cython.  Everything in this
-tutorial should work with Cython 0.11.2 and newer, unless a footnote
-says otherwise.
+use the instructions below to update Cython.
 
 Unlike most Python software, Cython requires a C compiler to be
 present on the system. The details of getting a C compiler varies
@@ -17,20 +15,29 @@ according to the system used:
 
  - **Linux** The GNU C Compiler (gcc) is usually present, or easily
    available through the package system. On Ubuntu or Debian, for
-   instance, the command ``sudo apt-get install build-essential`` will
-   fetch everything you need.
+   instance, it is part of the ``build-essential`` package. Next to a
+   C compiler, Cython requires the Python header files. On Ubuntu or
+   Debian, the command ``sudo apt-get install build-essential python3-dev``
+   will fetch everything you need.
 
  - **Mac OS X** To retrieve gcc, one option is to install Apple's
    XCode, which can be retrieved from the Mac OS X's install DVDs or
    from https://developer.apple.com/.
 
- - **Windows** A popular option is to use the open source MinGW (a
+ - **Windows** The CPython project recommends building extension modules 
+   (including Cython modules) with the same compiler that Python was
+   built with. This is usually a specific version of Microsoft Visual
+   C/C++ (MSVC) - see https://wiki.python.org/moin/WindowsCompilers. 
+   MSVC is the only compiler that Cython is currently tested with on 
+   Windows.  If you're having difficulty making setuptools detect
+   MSVC then `PyMSVC <https://github.com/kdschlosser/python_msvc>`_
+   aims to solve this.
+   
+   A possible alternative is the open source MinGW (a
    Windows distribution of gcc). See the appendix for instructions for
    setting up MinGW manually. Enthought Canopy and Python(x,y) bundle
    MinGW, but some of the configuration steps in the appendix might
-   still be necessary.  Another option is to use Microsoft's Visual C.
-   One must then use the same version which the installed Python was
-   compiled with.
+   still be necessary.
 
 .. dagss tried other forms of ReST lists and they didn't look nice
 .. with rst2latex.
@@ -41,7 +48,7 @@ The simplest way of installing Cython is by using ``pip``::
 
 
 The newest Cython release can always be downloaded from
-http://cython.org.  Unpack the tarball or zip file, enter the
+https://cython.org/.  Unpack the tarball or zip file, enter the
 directory, and then run::
 
   python setup.py install
@@ -59,4 +66,4 @@ with
 
 .. [Anaconda] https://docs.anaconda.com/anaconda/
 .. [Canopy] https://www.enthought.com/product/canopy/
-.. [Sage] W. Stein et al., Sage Mathematics Software, http://www.sagemath.org/
+.. [Sage] W. Stein et al., Sage Mathematics Software, https://www.sagemath.org/
diff --git a/docs/src/quickstart/jupyter.png b/docs/src/quickstart/jupyter.png
index 84b3543ad..34b38df6d 100644
--- a/docs/src/quickstart/jupyter.png
+++ b/docs/src/quickstart/jupyter.png
diff --git a/docs/src/quickstart/overview.rst b/docs/src/quickstart/overview.rst
index 1585f89fe..1a378e837 100644
--- a/docs/src/quickstart/overview.rst
+++ b/docs/src/quickstart/overview.rst
@@ -1,7 +1,7 @@
 Cython - an overview
 ====================
 
-[Cython] is a programming language that makes writing C extensions
+[Cython]_ is a programming language that makes writing C extensions
 for the Python language as easy as Python itself.  It aims to become
 a superset of the [Python]_ language which gives it high-level,
 object-oriented, functional, and dynamic programming.  Its main feature
@@ -44,13 +44,13 @@ thus merges the two worlds into a very broadly applicable programming
 language.
 
 .. [Cython] G. Ewing, R. W. Bradshaw, S. Behnel, D. S. Seljebotn et al.,
-   The Cython compiler, http://cython.org.
+   The Cython compiler, https://cython.org/.
 .. [IronPython] Jim Hugunin et al., https://archive.codeplex.com/?p=IronPython.
 .. [Jython] J. Huginin, B. Warsaw, F. Bock, et al.,
-   Jython: Python for the Java platform, http://www.jython.org.
+   Jython: Python for the Java platform, https://www.jython.org.
 .. [PyPy] The PyPy Group, PyPy: a Python implementation written in Python,
-   http://pypy.org.
+   https://pypy.org/.
 .. [Pyrex] G. Ewing, Pyrex: C-Extensions for Python,
-   http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/
+   https://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/
 .. [Python] G. van Rossum et al., The Python programming language,
    https://www.python.org/.