Merge docs repo

docs/.hgignore

@@ -0,0 +1,9 @@
+syntax: glob
+
+*.pyc
+*~
+.*.swp
+
+syntax: regexp
+^build/
+^_build/

docs/Makefile

@@ -0,0 +1,68 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html web htmlhelp latex changes linkcheck
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  web       to make files usable by Sphinx.web"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview over all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+
+clean:
+	-rm -rf build/*
+
+html:
+	mkdir -p build/html build/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
+	@echo
+	@echo "Build finished. The HTML pages are in build/html."
+
+web:
+	mkdir -p build/web build/doctrees
+	$(SPHINXBUILD) -b web $(ALLSPHINXOPTS) build/web
+	@echo
+	@echo "Build finished; now you can run"
+	@echo "  python -m sphinx.web build/web"
+	@echo "to start the server."
+
+htmlhelp:
+	mkdir -p build/htmlhelp build/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in build/htmlhelp."
+
+latex:
+	mkdir -p build/latex build/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in build/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	mkdir -p build/changes build/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
+	@echo
+	@echo "The overview file is in build/changes."
+
+linkcheck:
+	mkdir -p build/linkcheck build/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in build/linkcheck/output.txt."

docs/README

@@ -0,0 +1,14 @@
+Cython's entire documentation suite is currently being overhauled.
+
+For the time being, I'll use this page to post notes.
+
+The previous Cython documentation files are hosted at http://hg.cython.org/cython-docs
+
+
+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) Fix cython highlighter for cdef blocks

docs/_templates/layout.html

@@ -0,0 +1,14 @@
+{% extends "!layout.html" %}
+
+{% block footer %}
+{{ super() }}
+<script type="text/javascript">
+var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+</script>
+<script type="text/javascript">
+try {
+var pageTracker = _gat._getTracker("UA-6139100-3");
+pageTracker._trackPageview();
+} catch(err) {}</script>
+{% endblock %}

docs/conf.py

@@ -0,0 +1,163 @@
+# -*- coding: utf-8 -*-
+#
+# Cython documentation build configuration file, created by
+# sphinx-quickstart on Fri Apr 25 12:49:32 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys
+
+# If your extensions are in another directory, add it here.
+sys.path.append('sphinxext')
+
+# Import support for ipython console session syntax highlighting (lives
+# in the sphinxext directory defined above)
+import ipython_console_highlighting
+
+# General configuration
+# ---------------------
+
+# Use cython as the default syntax highlighting language, as python is a subset
+# this does the right thing
+highlight_language = 'cython'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['ipython_console_highlighting', 'cython_highlighting', 'sphinx.ext.pngmath', 'sphinx.ext.todo']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+exclude_patterns = ['py*', 'build']
+
+# General substitutions.
+project = 'Cython'
+copyright = '2011, Stefan Behnel, Robert Bradshaw, Dag Sverre Seljebotn, Greg Ewing, William Stein, Gabriel Gellner, et al.'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '0.15'
+# The full version, including alpha/beta/rc tags.
+release = '0.15pre'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# Options for HTML output
+# -----------------------
+
+# suffix for generated files
+html_file_suffix = '.html'
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# Include the Cython logo in the sidebar
+html_logo = '_static/cython-logo-light.png'
+
+# used a favicon!
+html_favicon = '_static/favicon.ico'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Content template for the index page.
+#html_index = ''
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+html_use_modindex = False
+
+# Don't generate and index
+html_use_index = False
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Cythondoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+#_stdauthor = r'Greg Ewig\\ Gabriel Gellner, editor'
+_stdauthor = r'Stefan Behnel, Robert Bradshaw, William Stein\\ Gary Furnish, Dag Seljebotn, Greg Ewing\\ Gabriel Gellner, editor'
+latex_documents = [
+    ('src/reference/index', 'reference.tex',
+     'Cython Reference Guide', _stdauthor, 'manual'),
+    ('src/tutorial/index', 'tutorial.tex',
+     'Cython Tutorial', _stdauthor, 'manual')
+]
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
+
+# todo
+todo_include_todos = True

docs/examples/tutorial/fib1/fib.pyx

@@ -0,0 +1,6 @@
+def fib(n):
+    """Print the Fibonacci series up to n."""
+    a, b = 0, 1
+    while b < n:
+        print b,
+        a, b = b, a + b

docs/examples/tutorial/fib1/setup.py

@@ -0,0 +1,9 @@
+from distutils.core import setup
+from distutils.extension import Extension
+from Cython.Distutils import build_ext
+
+setup(
+    cmdclass = {'build_ext': build_ext},
+    ext_modules = [Extension("fib", ["fib.pyx"])]
+)
+

docs/examples/tutorial/great_circle/c1.pyx

@@ -0,0 +1,12 @@
+import math
+
+def great_circle(lon1, lat1, lon2, lat2):
+    radius = 3956 # miles
+    x = math.pi/180.0
+
+    a = (90.0 - lat1)*x
+    b = (90.0 - lat2)*x
+    theta = (lon2 - lon1)*x
+    c = math.acos(math.cos(a)*math.cos(b) + math.sin(a)*math.sin(b)*math.cos(theta))
+
+    return radius*c

docs/examples/tutorial/great_circle/c2.pyx

@@ -0,0 +1,13 @@
+import math
+
+def great_circle(double lon1, double lat1, double lon2, double lat2):
+    cdef double radius = 3956 # miles
+    cdef double x = math.pi/180.0
+    cdef double a, b, theta, c
+
+    a = (90.0 - lat1)*x
+    b = (90.0 - lat2)*x
+    theta = (lon2 - lon1)*x
+    c = math.acos(math.cos(a)*math.cos(b) + math.sin(a)*math.sin(b)*math.cos(theta))
+
+    return radius*c

docs/examples/tutorial/great_circle/p1.py

@@ -0,0 +1,12 @@
+import math
+
+def great_circle(lon1, lat1, lon2, lat2):
+    radius = 3956 # miles
+    x = math.pi/180.0
+
+    a = (90.0 - lat1)*x
+    b = (90.0 - lat2)*x
+    theta = (lon2 - lon1)*x
+    c = math.acos(math.cos(a)*math.cos(b) + math.sin(a)*math.sin(b)*math.cos(theta))
+
+    return radius*c

docs/examples/tutorial/primes/primes.py

@@ -0,0 +1,15 @@
+def primes(kmax):
+    result = []
+    if kmax > 1000:
+        kmax = 1000
+    while k < kmax:
+        i = 0
+        while i < k and n % p[i] != 0:
+            i = i + 1
+        if i == k:
+            p[k] = n
+            k = k + 1
+            result.append(n)
+        n = n + 1
+    return result
+

docs/examples/tutorial/primes/primes.pyx

@@ -0,0 +1,19 @@
+def primes(int kmax):
+    cdef int n, k, i
+    cdef int p[1000]
+    result = []
+    if kmax > 1000:
+        kmax = 1000
+    k = 0
+    n = 2
+    while k < kmax:
+        i = 0
+        while i < k and n % p[i] != 0:
+            i = i + 1
+        if i == k:
+            p[k] = n
+            k = k + 1
+            result.append(n)
+        n = n + 1
+    return result
+

docs/examples/tutorial/primes/setup.py

@@ -0,0 +1,9 @@
+from distutils.core import setup
+from distutils.extension import Extension
+from Cython.Distutils import build_ext
+
+setup(
+    cmdclass = {'build_ext': build_ext},
+    ext_modules = [Extension("primes", ["primes.pyx"])]
+)
+

docs/index.rst

@@ -0,0 +1,11 @@
+
+Welcome to Cython's Documentation
+=================================
+
+.. toctree::
+   :maxdepth: 2
+
+   src/quickstart/index
+   src/tutorial/index
+   src/userguide/index
+   src/reference/index