language basics outline started

.hgignore

@@ -7,3 +7,9 @@ syntax: glob
 syntax: regexp
 ^build/
 ^_build/
+
+
+
+
+
+

NOTES

 
-1) Some css work should definately be done.
-2) Use local 'top-of-page' contents rather than the sidebar, imo.
-3) Provide a link from each (sub)section to the contents of the page.
-4)
\ No newline at end of file

README

-This is a collection of all the assorted pyrex/cython documentation assembled into
-a unified Python style Sphinx project. It is hoped that this will become the default
-documentation for the Cython tool set.
+Cython's entire documentation suite is currently being overhauled.
 
-Curently the files are hosted at:
-http://hg.cython.org/cython-docs
+For the time being, I will use this page to post notes to both myself and to any interested parties that come to view my progress.
+
+The prvious Cython documentation files are hosted at http://hg.cython.org/cython-docs
+
+For my vistors
+===============
+
+1) This is creative process not necessarily a predetermined blueprint of what I may have in mind.
+2) It's also an iterative process.
+3) All constructive thoughts, visions, and criticisms most welcome.. :)
+
+
+For me :)
+=========
+
+1) Some css work should definately be done.
+2) Use local 'top-of-page' contents rather than the sidebar, imo.
+3) Provide a link from each (sub)section to the TOC of the page.
+4) Temporarily using bold emphisis everywhere to signify special markup to be addressed later.
\ No newline at end of file

src/language_basics.rst

@@ -16,14 +16,90 @@ Languange Basics
 Cython File Types
 =================
 
-pyx
-===
+There are three file types in cython:
+* Definition files carry the `.pxd` suffix
+* Implementation files carry the `'.pyx suffix
+* Include files which carry the `.pxi` suffix
 
-pxd
-===
 
-pxi
-===
+
+Definition
+==========
+
+What can it contain?
+--------------------
+
+ * Any kind of C type declaration.
+ * `extern` C function or variable decarations.
+ * Module implementation declarations as well as definition parts of extension types.
+ * This also is a convenient place to put all declarations of functions, etc., for an
+   **external library**
+
+What can't it contain?
+----------------------
+
+ * Any non-extern C variable declaration.
+ * Implementations of C or Python functions.
+ * Python class definitions
+ * Python executable statements.
+ * Any declaration that is defined as **public** to make it accessible to other Cython modules.
+
+  * This is not necessary, as it is automatic.
+  * a **public** declaration is only needed to make it accessible to **external C code**.
+
+What else?
+----------
+
+cimport
+```````
+
+* Use the **cimport** statement, as you would Python's import statement, to access these files
+  from other definition or implementation files.
+* **cimport** does not need to be called in `.pyx` file for for `.pxd` file that has the
+  same name. This is automatic.
+* For cimport to find the stated definition file, the path to the file must be appended to the
+  `-I` option of the **cython compile command**.
+
+compilation order
+`````````````````
+
+* When a `.pyx` file is to be compiled, cython first checks to see if a corresponding `.pxd` file
+  exits and processes it first.
+
+
+
+Implementation
+===============
+
+What can it contain?
+--------------------
+
+* Basically anything Cythonic, but see below.
+
+What can't it contain?
+----------------------
+
+* There are some restrictions when it comes to **extension types**, if the extension type is
+  already defined else where... **more on this later**
+
+
+Include
+=======
+
+What can it contain?
+--------------------
+
+* Any Cythonic code really, because the entire file is textually embedded at the location
+  you prescribe. Think.. "C pre-processor".
+
+How do I use it?
+----------------
+
+* Include the `.pxi` file with an `include` statement like: `include "spamstuff.pxi`
+* The `include` statement can appear anywhere in your cython file and at any indentation level
+* The code in the `.pxi` file needs to be rooted at the "zero" indentation level.
+* The included code can itself contain other `include` statements.
+
 
 ===========
 Data Typing