From 97b6bb454113bfc499286dd66e492db98d3c8103 Mon Sep 17 00:00:00 2001
From: Peter Badida <KeyWeeUsr@users.noreply.github.com>
Date: Sun, 5 Nov 2017 13:42:36 +0100
Subject: [PATCH] Docs: Add section for Cython dependency

---
 doc/sources/conf.py                       |  6 +--
 doc/sources/installation/deps-cython.rst  | 19 +++++++++
 doc/sources/installation/installation.rst | 48 +++++++++++++++--------
 3 files changed, 54 insertions(+), 19 deletions(-)
 create mode 100644 doc/sources/installation/deps-cython.rst

diff --git a/doc/sources/conf.py b/doc/sources/conf.py
index 8385c04df..7adefffb3 100644
--- a/doc/sources/conf.py
+++ b/doc/sources/conf.py
@@ -224,10 +224,10 @@ from kivy import setupconfig
 replacements = {
     'cython_install': 'Cython==' + setupconfig.CYTHON_MAX,
     'cython_note': (
-        'This version of **Kivy requires at least Cython version {0}**, '
-        'and has been tested through {1}. Later versions may work, '
+        'Kivy {0} **requires at least Cython version {1}**, '
+        'and has been tested through {2}. Later versions may work, '
         'but as they have not been tested there is no guarantee.'
-    ).format(setupconfig.CYTHON_MIN, setupconfig.CYTHON_MAX)
+    ).format(version, setupconfig.CYTHON_MIN, setupconfig.CYTHON_MAX)
 }
 
 if setupconfig.CYTHON_BAD:
diff --git a/doc/sources/installation/deps-cython.rst b/doc/sources/installation/deps-cython.rst
new file mode 100644
index 000000000..4031539d4
--- /dev/null
+++ b/doc/sources/installation/deps-cython.rst
@@ -0,0 +1,19 @@
+.. _deps_cython:
+
+Cython
+======
+
+|cython_note|
+
+Known issues
+------------
+
+* 0.27 -> Kivy Cython declaration bug in 1.10.0 causes failing compilation
+
+Unsupported
+-----------
+
+* 0.27 - 0.27.2 -> Kivy doesn't compile on Python 3.4 with `MinGWPy
+  <http://mingwpy.github.io>`_ because of a used unexported symbol
+  during the compilation. For more details see `this issue.
+  <https://github.com/cython/cython/issues/1968>`_
diff --git a/doc/sources/installation/installation.rst b/doc/sources/installation/installation.rst
index 0efef5dd6..71d69e450 100755
--- a/doc/sources/installation/installation.rst
+++ b/doc/sources/installation/installation.rst
@@ -6,29 +6,30 @@ Installation
 We try not to reinvent the wheel, but to bring something innovative to the
 market. As a consequence, we're focused on our own code and use pre-existing,
 high quality third-party libraries where possible.
-To support the full, rich set of features that Kivy offers, several other libraries are
-required. If you do not use a specific feature (e.g. video playback), you
-don't need the corresponding dependency.
+
+To support the full, rich set of features that Kivy offers, several other
+libraries are required. If you do not use a specific feature (e.g. video
+playback), you don't need the corresponding dependency.
+
 That said, there is one dependency that Kivy **does** require:
 `Cython <http://cython.org>`_.
 
-|cython_note|
-
 In addition, you need a `Python <http://python.org/>`_ 2.x (2.7 <= x < 3.0)
-or 3.x (3.3 <= x)
-interpreter. If you want to enable features like windowing (i.e. open a Window),
-audio/video playback or spelling correction, additional dependencies must
-be available. For these, we recommend `SDL2 <https://www.libsdl.org/download-2.0.php>`_, `Gstreamer 1.x
-<http://www.gstreamer.net/>`_ and `PyEnchant
-<https://pythonhosted.org/pyenchant/>`_, respectively.
-
+or 3.x (3.3 <= x) interpreter. If you want to enable features like windowing
+(i.e. open a Window), audio/video playback or spelling correction, additional
+dependencies must be available. For these, we recommend
+`SDL2 <https://www.libsdl.org/download-2.0.php>`_,
+`Gstreamer 1.x <http://www.gstreamer.net/>`_ and
+`PyEnchant <https://pythonhosted.org/pyenchant/>`_ respectively.
 
 Other optional libraries (mutually independent) are:
 
-    * `OpenCV 2.0 <http://sourceforge.net/projects/opencvlibrary/>`_ -- Camera input.
-    * `Pillow <https://python-pillow.github.io/>`_ -- Image and text display.
-    * `PyEnchant <https://pythonhosted.org/pyenchant/>`_ -- Spelling correction.
-
+* `OpenCV 2.0 <http://sourceforge.net/projects/opencvlibrary/>`_
+  -- Camera input,
+* `Pillow <https://python-pillow.github.io/>`_
+  -- Image and text display,
+* `PyEnchant <https://pythonhosted.org/pyenchant/>`_
+  -- Spelling correction.
 
 That said, **DON'T PANIC**!
 
@@ -39,6 +40,21 @@ We just want you to know that there are alternatives to the defaults and give
 you an overview of the things Kivy uses internally.
 
 
+.. _installation_deps:
+
+Dependencies
+------------
+
+Here are listed dependencies required for Kivy to run and have/had issues
+in specific versions that broke our core functionality and Kivy either
+doesn't compile or can throw errors:
+
+.. toctree::
+    :maxdepth: 2
+
+    deps-cython
+
+
 Stable Version
 --------------