Merge pull request #2250 from gabrieldemarmiesse/transfer_reference

Transfered the Cython file types in the userguide.

docs/src/reference/language_basics.rst

@@ -12,6 +12,8 @@ Language Basics
 Cython File Types
 =================
 
+.. NOW IN USER GUIDE, DO NOT TOUCH
+
 There are three file types in Cython:
 
 * Implementation files carry a ``.pyx`` suffix

docs/src/tutorial/pxd_files.rst

+.. _pxd_files:
+
 pxd files
 =========
 

docs/src/userguide/language_basics.rst

@@ -538,8 +538,78 @@ Like other Python looping statements, break and continue may be used in the
 body, and the loop may have an else clause.
 
 
-The include statement
-=====================
+Cython file types
+=================
+
+There are three file types in Cython:
+
+* The implementation files, carrying a ``.py`` or ``.pyx`` suffix.
+* The definition files, carrying a ``.pxd`` suffix.
+* The include files, carrying a ``.pxi`` suffix.
+
+The implementation file
+-----------------------
+
+The implementation file, as the name suggest, contains the implementation
+of your functions, classes, extension types, etc. Nearly all the
+python syntax is supported in this file. Most of the time, a ``.py``
+file can be renamed into a ``.pyx`` file without changing
+any code, and Cython will retain the python behavior.
+
+It is possible for Cython to compile both ``.py`` and ``.pyx`` files.
+The name of the file isn't important if one wants to use only the Python syntax,
+and Cython won't change the generated code depending on the suffix used.
+Though, if one want to use the Cython syntax, using a ``.pyx`` file is necessary.
+
+In addition to the Python syntax, the user can also
+leverage Cython syntax (such as ``cdef``) to use C variables, can
+declare functions as ``cdef`` or ``cpdef`` and can import C definitions
+with :keyword:`cimport`. Many other Cython features usable in implementation files
+can be found throughout this page and the rest of the Cython documentation.
+
+There are some restrictions on the implementation part of some :ref:`extension-types`
+if the corresponding definition file also defines that type.
+
+.. note::
+
+    When a ``.pyx`` file is compiled, Cython first checks to see if a corresponding
+    ``.pxd`` file exists and processes it first. It acts like a header file for
+    a Cython ``.pyx`` file. You can put inside functions that will be used by
+    other Cython modules. This allows different Cython modules to use functions
+    and classes from each other without the Python overhead. To read more about
+    what how to do that, you can see :ref:`pxd_files`.
+
+
+The definition file
+-------------------
+
+A definition file is used to declare various things.
+
+Any C declaration can be made, and it can be also a declaration of a C variable or
+function implemented in a C/C++ file. This can be done with ``cdef extern from``.
+Sometimes, ``.pxd`` files are used as a translation of C/C++ header files
+into a syntax that Cython can understand. This allows then the C/C++ variable and
+functions to be used directly in implementation files with :keyword:`cimport`.
+You can read more about it in :ref:`external-C-code` and :ref:`wrapping-cplusplus`.
+
+It can also contain the definition part of an extension type and the declarations
+of functions for an external library.
+
+It cannot contain the implementations of any C or Python functions, or any
+Python class definitions, or any executable statements. It is needed when one
+wants to  access :keyword:`cdef` attributes and methods, or to inherit from
+:keyword:`cdef` classes defined in this module.
+
+.. note::
+
+    You don't need to (and shouldn't) declare anything in a declaration file
+    :keyword:`public` in order to make it available to other Cython modules; its mere
+    presence in a definition file does that. You only need a public
+    declaration if you want to make something available to external C code.
+
+
+The include statement and include files
+---------------------------------------
 
 .. warning::
     Historically the ``include`` statement was used for sharing declarations.