Commit 7c26bf33 authored by Peter Alexander's avatar Peter Alexander

language basics outline started

parent 19d3f32e
......@@ -7,3 +7,9 @@ syntax: glob
syntax: regexp
^build/
^_build/
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
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
......@@ -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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment