Pythonise the documentation according to #4187: Basic Tutorial (cython_tutorial.rst) (GH-4226)

See https://github.com/cython/cython/issues/4187

* .gitignore: add directory for docs build and cython_debug
* doc-requirements.txt: add sphinx-tabs
* conf.py: add and setup sphinx-tabs extension
* Create _static\css\tabs.css for customisation
* add "two-syntax-variants-used" file as a preface about the different typing variants

.gitignore

@@ -24,6 +24,7 @@ Demos/*/*.html
 /TEST_TMP/
 /build/
 /cython_build/
+cython_debug/
 /wheelhouse*/
 !tests/build/
 /dist/
@@ -42,6 +43,7 @@ callgrind.out.*
 
 .ipynb_checkpoints
 docs/build
+docs/_build
 
 tags
 TAGS

doc-requirements.txt

 sphinx==3.5.3
 sphinx-issues==1.2.0
+sphinx-tabs==3.0.0
 jupyter

docs/_static/css/tabs.css

+.sphinx-tabs {
+    margin-bottom: 1rem;
+}
+  
+[role="tablist"] {
+    border-bottom: 0px solid #a0b3bf;
+}
+  
+.sphinx-tabs-tab {
+    position: relative;
+    font-family: 'Helvetica Neue',Arial,Helvetica,sans-serif;
+    color: black;
+    line-height: 24px;
+    margin: 0;
+    font-size: 16px;
+    font-weight: 400;
+    background-color: rgba(255, 255, 255, 0);
+    border-radius: 5px 5px 5px 5px;
+    border: 0;
+    padding: 0.5rem 1.6rem;
+    margin-bottom: 0;
+}
+
+.sphinx-tabs-tab[aria-selected="true"] {
+    border: 2px solid gray;
+    border-bottom: 2px solid gray;
+    margin: -2px;
+    background-color: #efefef;
+    z-index: 999;  /* render on top*/
+}
+
+.sphinx-tabs-tab[aria-selected="false"] {
+    border: 2px solid #dddddd;
+    border-bottom: 2px solid #dddddd;
+    margin: -2px;
+    background-color: white;
+  }
+  
+.sphinx-tabs-tab:focus {
+    z-index: 1;
+    outline-offset: 1px;
+}
+  
+.sphinx-tabs-panel {
+    position: relative;
+    padding: 0rem;
+    border: 0px solid #a0b3bf;
+    margin: 0px 0px 0px 0px;
+    border-radius: 0 0 5px 5px;
+    border-top: 0;
+    background: white;
+}
+  
+.sphinx-tabs-panel.code-tab {
+    padding: 0.4rem;
+}
+  
+.sphinx-tab img {
+    margin-bottom: 24 px;
+}

docs/conf.py

@@ -39,6 +39,7 @@ extensions = [
     'sphinx.ext.intersphinx',
     'sphinx.ext.autodoc',
     'sphinx_issues',  # if this is missing, pip install sphinx-issues
+    'sphinx_tabs.tabs',  # if this is missing, pip install sphinx-tabs
     ]
 
 try: import rst2pdf
@@ -133,6 +134,10 @@ imgmath_image_format = "svg"
 
 issues_github_path = "cython/cython"
 
+# For sphinx-tabs
+
+sphinx_tabs_disable_tab_closing = True
+
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -174,6 +179,11 @@ html_favicon = "_static/favicon.ico"
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# Overwriting css from extensions
+html_context = {
+    'css_files': ['_static/css/tabs.css'],
+}
+
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'

docs/examples/tutorial/cython_tutorial/primes.py

+def primes(nb_primes: cython.int):
+    i: cython.int
+    p: cython.int[1000]
+
+    if nb_primes > 1000:
+        nb_primes = 1000
+
+    if not cython.compiled:  # Only if regular Python is running
+        p = [0] * 1000       # Make p work almost like a C array
+
+    len_p: cython.int = 0  # The current number of elements in p.
+    n: cython.int = 2
+    while len_p < nb_primes:
+        # Is n prime?
+        for i in p[:len_p]:
+            if n % i == 0:
+                break
+
+        # If no break occurred in the loop, we have a prime.
+        else:
+            p[len_p] = n
+            len_p += 1
+        n += 1
+
+    # Let's copy the result into a Python list:
+    result_as_list = [prime for prime in p[:len_p]]
+    return result_as_list

docs/examples/tutorial/cython_tutorial/primes.pyx

 def primes(int nb_primes):
     cdef int n, i, len_p
     cdef int p[1000]
+
     if nb_primes > 1000:
         nb_primes = 1000
 
+
+
+
     len_p = 0  # The current number of elements in p.
     n = 2
     while len_p < nb_primes:
@@ -18,6 +22,6 @@ def primes(int nb_primes):
             len_p += 1
         n += 1
 
-    # Let's return the result in a python list:
+    # Let's copy the result into a Python list:
     result_as_list = [prime for prime in p[:len_p]]
     return result_as_list

docs/examples/tutorial/cython_tutorial/primes_cpp.py

+# distutils: language=c++
+
+import cython
+from cython.cimports.libcpp.vector import vector
+
+def primes(nb_primes: cython.uint):
+    i: cython.int
+    p: vector[cython.int]
+    p.reserve(nb_primes)  # allocate memory for 'nb_primes' elements.
+
+    n: cint = 2
+    while p.size() < nb_primes:  # size() for vectors is similar to len()
+        for i in p:
+            if n % i == 0:
+                break
+        else:
+            p.push_back(n)  # push_back is similar to append()
+        n += 1
+
+    # If possible, C values and C++ objects are automatically
+    # converted to Python objects at need.
+    return p  # so here, the vector will be copied into a Python list.

docs/examples/tutorial/cython_tutorial/primes_cpp.pyx

 # distutils: language=c++
 
+
 from libcpp.vector cimport vector
 
 def primes(unsigned int nb_primes):
@@ -16,6 +17,6 @@ def primes(unsigned int nb_primes):
             p.push_back(n)  # push_back is similar to append()
         n += 1
 
-    # Vectors are automatically converted to Python
-    # lists when converted to Python objects.
-    return p
+    # If possible, C values and C++ objects are automatically
+    # converted to Python objects at need.
+    return p  # so here, the vector will be copied into a Python list.

docs/examples/tutorial/cython_tutorial/primes_python.py

-def primes_python(nb_primes):
+def primes(nb_primes):
     p = []
     n = 2
     while len(p) < nb_primes:

docs/examples/tutorial/cython_tutorial/setup.py

-from setuptools import setup
-from Cython.Build import cythonize
-
-setup(
-    ext_modules=cythonize("fib.pyx"),
-)

docs/src/cimport-warning

+.. warning::
+
+    This code uses an external native (non-Python) library through a ``cimport``.
+    Cython compilation enables this, but there is no support for this from
+    plain Python. Trying to run this code from Python (without compilation)
+    will fail when accessing the external library.
+    This is described in more detail in :ref:`calling-c-functions`.

docs/src/tutorial/pure.rst

@@ -340,6 +340,8 @@ improve the type analysis in Cython.
 Tips and Tricks
 ---------------
 
+.. _calling-c-functions:
+
 Calling C functions
 ^^^^^^^^^^^^^^^^^^^
 

docs/src/two-syntax-variants-used

+This page uses two different syntax variants: the Cython specific ``cdef`` syntax
+and static Cython type declarations in
+:ref:`pure Python code <pep484_type_annotations>`,
+following `PEP-484 <https://www.python.org/dev/peps/pep-0484/>`_ type hints
+and `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ variable annotations.
+To make good use of the latter, including C data types, etc., you need
+the special ``cython`` module, which you can import with
+
+.. code-block:: python
+
+    import cython
+
+in the Python module that you want to compile.