From 8cbbb51dcb1b83cdccdf4235494bde2f57989cce Mon Sep 17 00:00:00 2001
From: "R. Tyler Ballance" <tyler@slide.com>
Date: Mon, 1 Jun 2009 10:45:21 -0700
Subject: Update more sphinx based documentation, this pretty much finishes the
 transfer from the Markdown stuff I had previously

Signed-off-by: R. Tyler Ballance <tyler@slide.com>
---
 www/conf.py                      | 10 +++----
 www/documentation.rst            | 12 ++++++++
 www/download.rst                 | 17 +++++++++++
 www/index.rst                    | 11 +++++--
 www/recipes/inheritance.rst      | 62 ++++++++++++++++++++++++++++++++++++++++
 www/recipes/precompiled.rst      | 59 ++++++++++++++++++++++++++++++++++++++
 www/recipes/staticmethod.rst     | 54 ++++++++++++++++++++++++++++++++++
 www/recipes/writing_a_recipe.rst |  4 +++
 www/roadmap.rst                  | 25 ++++++++++++++++
 9 files changed, 246 insertions(+), 8 deletions(-)
 create mode 100644 www/documentation.rst
 create mode 100644 www/recipes/inheritance.rst
 create mode 100644 www/recipes/precompiled.rst
 create mode 100644 www/recipes/staticmethod.rst
 create mode 100644 www/recipes/writing_a_recipe.rst

(limited to 'www')

diff --git a/www/conf.py b/www/conf.py
index 49b132f..4c28ecf 100644
--- a/www/conf.py
+++ b/www/conf.py
@@ -91,7 +91,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+html_theme = 'sphinxdoc'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -124,7 +124,7 @@ 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'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -138,16 +138,16 @@ html_use_smartypants = True
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_use_modindex = True
+html_use_modindex = True
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
diff --git a/www/documentation.rst b/www/documentation.rst
new file mode 100644
index 0000000..fd7c086
--- /dev/null
+++ b/www/documentation.rst
@@ -0,0 +1,12 @@
+User Documentation
+==================
+
+Simple Recipes
+--------------
+.. toctree::
+   :maxdepth: 2
+
+   recipes/inheritance.rst
+   recipes/precompiled.rst
+   recipes/staticmethod.rst
+   recipes/writing_a_recipe.rst
diff --git a/www/download.rst b/www/download.rst
index 713d325..922e9eb 100644
--- a/www/download.rst
+++ b/www/download.rst
@@ -1,2 +1,19 @@
 Downloading Cheetah
 ===================
+
+The most recent stable release of Cheetah **v2.2.0** which was released on
+May 17th, 2009.
+
+Download v2.2.0
+^^^^^^^^^^^^^^^
+* `v2.2.0 tarball <http://github.com/cheetahtemplate/cheetah/tarball/v2.2.0>`_
+* `v2.2.0 zip <http://github.com/cheetahtemplate/cheetah/zipball/v2.2.0>`_
+
+You can keep up to date with release candidates or other downloads of Cheetah by 
+visiting the `cheetahtemplate GitHub page <http://github.com/cheetahtemplate/cheetah/downloads>`_
+
+**Note to Windows users:** You should install the compiled version of Cheetah's 
+NameMapper. It is dramatically faster than the pure Python version, in the source
+tree you can find compiled versions for Python 2.4: namemapper.pyd2.4, 
+Python 2.5: namemapper.pyd2.5. Install it wherever your system puts 
+Cheetah/NameMapper.py. Strip the version numbers off the filename.
diff --git a/www/index.rst b/www/index.rst
index 2cd0096..bcfa124 100644
--- a/www/index.rst
+++ b/www/index.rst
@@ -17,17 +17,22 @@ At its core, Cheetah is a domain-specific language for markup generation and
 templating which allows for full integration with existing Python code but also 
 offers extensions to traditional Python syntax to allow for easier text-generation.
 
+Talk Cheetah
+^^^^^^^^^^^^
+You can get involved and talk with Cheetah developers on the `Cheetah mailing list <http://lists.sourceforge.net/lists/listinfo/cheetahtemplate-discuss>`_
+(*cheetahtemplate-discuss@lists.sourceforge.net*) or on the **IRC** channel: 
+**#cheetah** on `Freenode <http://freenode.net/>`_
 
-
-Contents:
+Contents
 ^^^^^^^^^
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    developers.rst
    download.rst
    roadmap.rst
+   documentation.rst
 
 
 Cheetah in a nutshell
diff --git a/www/recipes/inheritance.rst b/www/recipes/inheritance.rst
new file mode 100644
index 0000000..983e044
--- /dev/null
+++ b/www/recipes/inheritance.rst
@@ -0,0 +1,62 @@
+Basic Inheritance
+=================
+
+Introduction
+------------
+Cheetah, like Python, is an object-oriented language if you so choose to 
+use it in that fashion. That is to say that you can use Cheetah in with 
+object-oriented principles *or* you can use Cheetah in a strictly functional
+sense, like Python, Cheetah does not place restrictions on these barriers.
+
+While Cheetah is not strictly Python, it was designed as such to interoperate,
+particularly with the notion of classes, with Python itself. In effect you can 
+define Python classes that inherit and extend from Cheetah-derived classes and 
+vice versa. For this, Cheetah defines a few **directives** (denoted with the `\#` 
+hash-mark) that are of some help, the most important one being the `\#extends`
+directive, with others playing important roles like `\#import`, `\#attr` and `\#super`
+
+In this recipe/tutorial I intend to explain and define a few key inheritance
+patterns with Cheetah, being:
+
+* A Cheetah Template inheriting from Python
+* Python inheriting from a Cheetah Template
+* Cheetah Templates and "*mixins*"
+
+This document also operates on the assumption that the reader is at least 
+somewhat familiar with the basic tenets of object-oriented programming in 
+Python.
+
+
+Cheetah inheriting from Python
+------------------------------
+Whether or not you are aware of it, Cheetah templates are always inheriting from 
+a Python class by default. Unless otherwise denoted, Cheetah templates are compiled 
+to Python classes that subclass from the `Cheetah.Template.Template` class.
+
+What if you would like to introduce your own Template base class? Easily acheived by
+defining your own Template class in a Python module, for example::
+
+    import Cheetah.Template
+
+    class CookbookTemplate(Cheetah.Template.Template):
+        _page = 'Cookbook'
+        author = 'R. Tyler Ballance'
+        def pageName(self):
+            return self._page or 'Unknown'
+
+**Figure 1. cookbook.py**
+
+For this example, I want all my subclasses of the `CookbookTemplate` to define a 
+page author which will be used in some shared rendering code, to accomplish this
+my templates will need to subclass from `CookbookTemplate` explicitly instead of 
+implicitly subclassing from `Cheetah.Template.Template`::
+
+    #import cookbook
+    #extends cookbook.CookbookTemplate
+    #attr author = 'Tavis Rudd'
+
+    ## The rest of my recipe template would be below
+
+**Figure 2. recipe1.tmpl**
+
+
diff --git a/www/recipes/precompiled.rst b/www/recipes/precompiled.rst
new file mode 100644
index 0000000..4480724
--- /dev/null
+++ b/www/recipes/precompiled.rst
@@ -0,0 +1,59 @@
+Precompiled Templates
+=====================
+
+Why bother?
+-----------
+Since Cheetah supports two basic modes: dynamic and precompiled templates, you have 
+a lot of options when it comes to utilizing Cheetah, particularly in web environments.
+
+There is added speed to be gained by using pre-compiled templates, especially when
+using mod_python with Apache. Precompiling your templates means Apache/mod_python
+can load your template's generated module into memory and then execution is only
+limited by the speed of the Python being executed, and not the Cheetah compiler.
+You can further optimize things by then pre-compiling the generated Python files 
+(.py) down to Python byte-code (.pyc) so save cycles interpreting the Python.
+
+
+Basic Pre-compilation
+---------------------
+Suppose you have a template that looks something like this::
+
+    #attr title = "This is my Template"
+    <html>
+        <head>
+            <title>\${title}</title>
+        </head>
+        <body>
+            Hello \${who}!
+        </body>
+    </html>
+**Figure 1. hello.tmpl**
+
+In order to compile this down to a Python file, you need to only execute the 
+`cheetah compile hello.tmpl` command. The results will be a Python file (.py) 
+which you can then treat as any other Python module in your code base.
+
+
+Importing and lookup
+--------------------
+Typically for the template in *Figure 1*, I could easily import it post-compilation
+as any other Python module::
+
+    from templates import hello
+
+    def myMethod():
+        tmpl = hello.hello(searchList=[{'who' : 'world'}])
+        results = tmpl.respond()
+
+**Figure 2. runner.py**
+
+*Note:* If you use the `\#implements` directive, `respond` may not be your "main 
+method" for executing the Cheetah template. You can adjust the example above in 
+*Figure 2* by using `getattr()` to make the lookup of the main method dynamic::
+
+    def myMethod():
+        tmpl = hello.hello(searchList=[{'who' : 'world'}])
+        mainMethod = getattr(tmpl, '_mainCheetahMethod_for_%s' % tmpl.__class__.__name__)
+        results = getattr(tmpl, mainMethod)()
+
+**Figure 3. Dynamic runner.py**
diff --git a/www/recipes/staticmethod.rst b/www/recipes/staticmethod.rst
new file mode 100644
index 0000000..53192e1
--- /dev/null
+++ b/www/recipes/staticmethod.rst
@@ -0,0 +1,54 @@
+@staticmethod and @classmethod
+==============================
+
+Refer the Python's documentation if you're unfamiliar with either 
+`@staticmethod <http://docs.python.org/library/functions.html#staticmethod>`_ or 
+`@classmethod <http://docs.python.org/library/functions.html#classmethod>`_ and their uses in Python, as they
+pertain to their uses in Cheetah as well. Using `@staticmethod <http://docs.python.org/library/functions.html#staticmethod>`_ it's 
+trivial to create *utility templates* which are common when using 
+Cheetah for web development. These *utility templates* might contain
+a number of small functions which generate useful snippets of markup.
+
+For example::
+
+    #def copyright()
+        #import time
+        &copy; CheetahCorp, Inc. $time.strftime('%Y', time.gmtime())
+    #end def
+
+**Figure 1, util.tmpl**
+
+Prior to version **v2.2.0** of Cheetah, there wasn't really an easy means
+of filling templates with bunches of these small utility functions. In 
+**v2.2.0** however, you can decorate these methods with `#@staticmethod` 
+and use "proper" Python syntax for calling them, **fig 1** revisited::
+
+    #@staticmethod
+    #def copyright()
+        #import time
+        &copy; CheetahCorp, Inc. $time.strftime('%Y', time.gmtime())
+    #end def
+    
+**Figure 1.1, util.tmpl**
+
+With the addition of the `@staticmethod <http://docs.python.org/library/functions.html#staticmethod>`_ decorator, the `copyright()` 
+function can now be used without instantiating an instance of the `util`
+template class. In effect::
+
+    #from util import util
+
+    <strong>This is my page</strong>
+    <br/>
+    <hr noshade/>
+    $util.copyright()
+
+**Figure 2, index.tmpl**
+
+
+This approach is however no means to structure anything complex, 
+`@staticmethod <http://docs.python.org/library/functions.html#staticmethod>`_ and `@classmethod <http://docs.python.org/library/functions.html#classmethod>`_ use in Cheetah is not meant as a 
+replacement for properly structured class hierarchies (which 
+Cheetah supports). That said if you are building a web application
+`@staticmethod <http://docs.python.org/library/functions.html#staticmethod>`_/`@classmethod <http://docs.python.org/library/functions.html#classmethod>`_ are quite useful for the little snippets 
+of markup, etc that are needed (Google AdSense blocks, footers, 
+banners, etc).
diff --git a/www/recipes/writing_a_recipe.rst b/www/recipes/writing_a_recipe.rst
new file mode 100644
index 0000000..6b1cbaa
--- /dev/null
+++ b/www/recipes/writing_a_recipe.rst
@@ -0,0 +1,4 @@
+Writing a "Recipe"
+=================
+
+This document isn't quite there yet ;)
diff --git a/www/roadmap.rst b/www/roadmap.rst
index a78709a..48fe964 100644
--- a/www/roadmap.rst
+++ b/www/roadmap.rst
@@ -1,2 +1,27 @@
 Cheetah Roadmap
 ===============
+
+Cheetah v2.2
+------------
+The first release in the v2.2 series (*v2.2.0*) introduced an overhaul of 
+Cheetah's string handling to convert everything internally to use `unicode()`
+objects instead of encoded string buffers. 
+
+The subsequent releases in the v2.2 series are planned to have a number of 
+important upgrades to Cheetah's infrastructure:
+
+* Built-in Django support
+* Cleaner code generation 
+* Finish and document #defmacro support
+
+Cheetah v2.3
+------------
+*still in planning*
+
+The third major series in the Cheetah 2 line of releases will have one focal point, **performance**
+
+Cheetah v3.0
+------------
+*still in planning*
+
+Cheetah 3000 will be the seminal milestone for running Cheetah on Python 3.0
-- 
cgit v1.2.1