languge basics outline

NOTES

-

README

 Cython's entire documentation suite is currently being overhauled.
 
-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.
+For the time being, I'll use this page to post notes.
 
-The prvious Cython documentation files are hosted at http://hg.cython.org/cython-docs
+The previous 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 :)
-=========
+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 TOC of the page.
-4) Temporarily using bold emphisis everywhere to signify special markup to be addressed later.
+4) Fix cython highlighter for cdef blocks
\ No newline at end of file

TODO

-* Make a Pygments lexer for cython/pyrex so we get nice color coding. [Partially Done]
-* Fix up the latex style file so that boxes are not messed up when we have
-  code examples.
-* Put on my writing hat, and do an overhaul of the structure of the docs so
-  that it is faster to navigate. I will be using the python doc structure as a
-  reference.
-* Get some simple howto's written.
-* Thinking if there is an easy way to test the cython code in the docs so that
-  I can ensure accuracy.
-

index.rst

 
-Welcome to Cython's Users Guide
-=================================
+Welcome to Cython's Reference Guide
+===================================
 
 Contents:
 

src/language_basics.rst

@@ -16,14 +16,15 @@ Languange Basics
 Cython File Types
 =================
 
+.. contents::
+    :local:
+
 There are three file types in cython:
 
-* Definition files carry a `.pxd` suffix
-* Implementation files carry a `.pyx` suffix
-* Include files which carry a `.pxi` suffix
+* Definition files carry a ``.pxd`` suffix
+* Implementation files carry a ``.pyx`` suffix
+* Include files which carry a ``.pxi`` suffix
 
-.. contents::
-    :local:
 
 Definition File
 ===============
@@ -32,7 +33,7 @@ What can it contain?
 --------------------
 
 * Any kind of C type declaration.
-* `extern` C function or variable decarations.
+* ``extern`` C function or variable decarations.
 * Declarations for module implementations.
 * The definition parts of **extension types**.
 * All declarations of functions, etc., for an **external library**
@@ -57,15 +58,15 @@ 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
+* **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**.
+  ``-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
+* When a ``.pyx`` file is to be compiled, cython first checks to see if a corresponding ``.pxd`` file
   exits and processes it first.
 
 
@@ -92,15 +93,15 @@ What can it contain?
 --------------------
 
 * Any Cythonic code really, because the entire file is textually embedded at the location
-  you prescribe. Think.. "C pre-processor".
+  you prescribe.
 
 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.
+* 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.
 
 
 ===========
@@ -110,12 +111,109 @@ Data Typing
 .. contents::
     :local:
 
+..
+    I think having paragraphs like this should only be in the tutorial which
+    we can link to from here
+
+As a dynamic language, Python encourages a programming style of considering classes and objects in terms of their methods and attributes, more than where they fit into the class hierarchy.
+
+This can make Python a very relaxed and comfortable language for rapid development, but with a price - the ‘red tape’ of managing data types is dumped onto the interpreter. At run time, the interpreter does a lot of work searching namespaces, fetching attributes and parsing argument and keyword tuples. This run-time ‘late binding’ is a major cause of Python’s relative slowness compared to ‘early binding’ languages such as C++.
+
+However with Cython it is possible to gain significant speed-ups through the use of ‘early binding’ programming techniques.
+
+The cdef Statement
+==================
+
+The ``cdef`` statement is used to make C level declarations for:
+
+:Variables:
+
+::
+
+    cdef int i, j, k
+    cdef float f, g[42], *h
+
+:Structs:
+
+::
+
+    cdef struct Grail:
+        int age
+        float volume
+
+:Unions:
+
+::
+
+    cdef union Food:
+        char *spam
+        float *eggs
+
+
+:Enums:
+
+::
+
+    cdef enum CheeseType:
+        cheddar, edam,
+        camembert
+
+    cdef enum CheeseState:
+        hard = 1
+        soft = 2
+        runny = 3
+
+:Funtions:
+
+::
+
+    cdef int eggs(unsigned long l, float f):
+        ...
+
+:Extenstion Types:
+
+::
+
+    cdef class Spam:
+        ...
+
+
+.. note::
+    Constants can be defined by using an anonymous enum::
+
+        cdef enum:
+            tons_of_spam = 3
+
+
 Grouping
 ========
 
+A series of declarations can grouped into a ``cdef`` block::
+
+        cdef:
+            struct Spam:
+                int tons
+
+            int i
+            float f
+            Spam *p
+
+            void f(Spam *s):
+            print s.tons, "Tons of spam"
+
+
 Parameters
 ==========
 
+* All the different **function** types can be declared to have C data types.
+* Use normal C declaration syntax.
+* **Python callable functions** can also be declared with C data types.
+
+ * As these parameters are passed into the Python function, they magically **convert** to
+   the specified C typed value.
+ * See also... **link the various areas that detail this**
+
+
 Conversion
 ==========
 
@@ -155,6 +253,7 @@ Error and Exception Handling
 Conditional Compilation
 =======================
 
+
 Compile-Time Definitions
 =========================