From ba9b0e647bff1bf0c437ab204ddf11783ed698f8 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 1 May 2009 10:26:57 +0000 Subject: Merge "c-free" branch to trunk. --- docs/narr/install.rst | 73 ++++++-------------- docs/narr/introduction.rst | 167 ++++++++++++++++++++++----------------------- docs/narr/project.rst | 4 +- docs/narr/templates.rst | 80 +++++++++------------- 4 files changed, 139 insertions(+), 185 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 8eb0ae978..81294e896 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -13,31 +13,26 @@ done primarily under Python 2.4. :mod:`repoze.bfg` does *not* run under any version of Python before 2.4, and does *not* run under Python 3.X. -.. warning:: To succesfully install :mod:`repoze.bfg`, you will need - an environment capable of compiling C code (e.g. ``XCode Tools`` - will need to be installed if you're using MacOS X, and ``gcc`` and - other build tools will need to be installed if you're using other - UNIXlike systems). See the system's documentation about installing - this software. Additionally, the Python development libraries for - your Python version will need to be installed and the ``lixbml2`` - and ``libxslt`` development libraries will need to be installed. - These requirements are often satisfied by installing the - ``python-devel``, ``libxml2-devel`` and ``libxslt-devel`` packages - into your system. You will also need :term:`setuptools` installed +.. note:: You will need :term:`setuptools` installed on within your Python system in order to run the ``easy_install`` command. -At the time of this writing, ``repoze.bfg`` will not install on -Windows systems unless you have development tools (e.g. *Visual C++*) -installed. +.. note:: As of version 0.8.0, installation of :mod:`repoze.bfg` does + not require the compilation of any C code, so you do not need to + have development tools installed on the target machine. -.. note:: If you'd like to help produce and maintain a version of - :mod:`repoze.bfg` that works on Windows, we'd love to hear from - you. There's nothing intrinsic about :mod:`repoze.bfg` that would - prevent it from running on Windows, but none of the current - developers use the platform. Please contact us via the `repoze.dev - maillist `_ if you'd - like to try to tackle the job of compilation and maintenance. +Although BFG is known to run properly on all Unix-like systems, at the +time of this writing, ``repoze.bfg`` is not tested on Windows systems. +It might run; it might not. There's nothing intrinsic about +:mod:`repoze.bfg` that would prevent it from running on Windows, but +none of the current developers use the platform. Likewise for +platforms like Jython, and Google App Engine; it may run, it may not. + +.. note:: If you'd like to help make sure :mod:`repoze.bfg` keeps +.. running on your favorite alternate platform, we'd love to hear from + you. Please contact us via the `repoze.dev maillist + `_ if you'd like to + contribute. Installing :mod:`repoze.bfg` ---------------------------- @@ -70,7 +65,7 @@ can usually install a setuptools package using your system's package manager. If you cannot do this, or if you're using a self-installed version of Python, you will need to install setuptools "by hand". Installing setuptools "by hand" is always a reasonable thing to do, -even if your package manager already has a prechewed version of +even if your package manager already has a pre-chewed version of setuptools for installation. To install setuptools by hand, first download `ez_setup.py @@ -146,46 +141,18 @@ virtualenv (``bfgenv``) directory: :mod:`repoze.bfg` cannot be installed from PyPI. This command will take longer than the previous ones to complete, as it -compiles a number of dependencies. +downloads and installs a number of dependencies. What Gets Installed ~~~~~~~~~~~~~~~~~~~ When you ``easy_install`` :mod:`repoze.bfg`, various Zope libraries, -WebOb, Paste, PasteScript, and PasteDeploy libraries are installed. +various Chameleon libraries, WebOb, Paste, PasteScript, and +PasteDeploy libraries are installed. Additionally, as shown in the next section, PasteScript (aka *paster*) templates will be registered that make it easy to start a new :mod:`repoze.bfg` project. -Troubleshooting ---------------- - -If ``lxml`` Fails to Compile During ``easy_install`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If the installation of :mod:`repoze.bfg` fails due to problems -compiling ``lxml``, you should try installing ``lxml`` before -installing :mod:`repoze.bfg`. To do so, invoke ``easy_install``, -instructing ``lxml`` to download its own copy of ``libxml2``:: - - $ STATIC_DEPS=true bin/easy_install lxml - -Once that completes, you can start a subsequent ``easy_install`` of -:mod:`repoze.bfg` as per the instructions above; it should then work. - -If You Can't Install Via ``easy_install`` (Alternate Installation) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you can't get :mod:`repoze.bfg` installed using ``easy_install`` -because ``lxml`` fails to compile on your system, you can try the -`repoze.bfg buildout -`_. This -installation mechanism builds known-compatible ``libxml2`` and -``libxslt`` from source and causes ``lxml`` to link against these -instead of your system packages, as version incompatibilities between -system packages and ``lxml`` versions are typically to blame for -compilation problems. - diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 83159dc45..072c6d8bf 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -147,90 +147,89 @@ It's Tested *If it ain't tested, it's broke.* We strive to test :mod:`repoze.bfg` completely. Below a run of the ``nosetests`` command configured to show code coverage information (run against the :mod:`repoze.bfg` -trunk just before the 0.6.8 release). +trunk sometime before the 0.8.0 release). .. code-block:: bash - [chrism@vitaminf trunk]$ python setup.py nosetests - running nosetests - running egg_info - writing requirements to repoze.bfg.egg-info/requires.txt - writing repoze.bfg.egg-info/PKG-INFO - writing namespace_packages to repoze.bfg.egg-info/namespace_packages.txt - writing top-level names to repoze.bfg.egg-info/top_level.txt - writing dependency_links to repoze.bfg.egg-info/dependency_links.txt - writing entry points to repoze.bfg.egg-info/entry_points.txt - writing manifest file 'repoze.bfg.egg-info/SOURCES.txt' - running build_ext - ............................................................................ - ............................................................................ - ............................................................................ - ............................................................................ - .......................................................................... - Name Stmts Exec Cover Missing - ---------------------------------------------------------------------- - repoze.bfg 1 1 100% - repoze.bfg.chameleon_genshi 44 44 100% - repoze.bfg.chameleon_text 48 48 100% - repoze.bfg.chameleon_zpt 44 44 100% - repoze.bfg.events 18 18 100% - repoze.bfg.functional 14 14 100% - repoze.bfg.includes 0 0 100% - repoze.bfg.interfaces 71 71 100% - repoze.bfg.location 42 42 100% - repoze.bfg.log 9 9 100% - repoze.bfg.lru 77 77 100% - repoze.bfg.path 12 12 100% - repoze.bfg.push 16 16 100% - repoze.bfg.registry 65 65 100% - repoze.bfg.request 16 16 100% - repoze.bfg.router 137 137 100% - repoze.bfg.security 150 150 100% - repoze.bfg.settings 24 24 100% - repoze.bfg.template 10 10 100% - repoze.bfg.templating 17 17 100% - repoze.bfg.testing 209 209 100% - repoze.bfg.tests 0 0 100% - repoze.bfg.tests.fixtureapp 0 0 100% - repoze.bfg.tests.fixtureapp.models 3 3 100% - repoze.bfg.tests.fixtureapp.views 4 4 100% - repoze.bfg.tests.grokkedapp 5 5 100% - repoze.bfg.tests.routesapp 0 0 100% - repoze.bfg.tests.routesapp.models 3 3 100% - repoze.bfg.tests.routesapp.views 4 4 100% - repoze.bfg.tests.test_chameleon_genshi 157 157 100% - repoze.bfg.tests.test_chameleon_text 172 172 100% - repoze.bfg.tests.test_chameleon_zpt 161 161 100% - repoze.bfg.tests.test_events 59 59 100% - repoze.bfg.tests.test_integration 127 127 100% - repoze.bfg.tests.test_location 83 83 100% - repoze.bfg.tests.test_log 11 11 100% - repoze.bfg.tests.test_lru 74 74 100% - repoze.bfg.tests.test_push 29 29 100% - repoze.bfg.tests.test_registry 112 112 100% - repoze.bfg.tests.test_router 668 668 100% - repoze.bfg.tests.test_security 464 464 100% - repoze.bfg.tests.test_settings 83 83 100% - repoze.bfg.tests.test_template 73 73 100% - repoze.bfg.tests.test_templating 45 45 100% - repoze.bfg.tests.test_testing 375 375 100% - repoze.bfg.tests.test_traversal 579 579 100% - repoze.bfg.tests.test_url 95 95 100% - repoze.bfg.tests.test_urldispatch 298 298 100% - repoze.bfg.tests.test_view 418 418 100% - repoze.bfg.tests.test_wsgi 75 75 100% - repoze.bfg.tests.test_xslt 191 191 100% - repoze.bfg.tests.test_zcml 608 608 100% - repoze.bfg.traversal 167 167 100% - repoze.bfg.url 35 35 100% - repoze.bfg.urldispatch 146 146 100% - repoze.bfg.view 76 76 100% - repoze.bfg.wsgi 23 23 100% - repoze.bfg.xslt 57 57 100% - repoze.bfg.zcml 246 244 99% 168-169 - ---------------------------------------------------------------------- - TOTAL 6750 6748 99% - ---------------------------------------------------------------------- - Ran 378 tests in 10.784s - - OK + [chrism@vitaminf c-less]$ env/bin/python setup.py nosetests + running nosetests + running egg_info + writing requirements to repoze.bfg.egg-info/requires.txt + writing repoze.bfg.egg-info/PKG-INFO + writing namespace_packages to repoze.bfg.egg-info/namespace_packages.txt + writing top-level names to repoze.bfg.egg-info/top_level.txt + writing dependency_links to repoze.bfg.egg-info/dependency_links.txt + writing entry points to repoze.bfg.egg-info/entry_points.txt + writing manifest file 'repoze.bfg.egg-info/SOURCES.txt' + running build_ext + ........................................................................... + ........................................................................... + ........................................................................... + ........................................................................... + ........................................................................... + ......... + Name Stmts Exec Cover Missing + -------------------------------------------------------------------- + repoze.bfg 0 0 100% + repoze.bfg.chameleon_text 48 48 100% + repoze.bfg.chameleon_zpt 44 44 100% + repoze.bfg.events 18 18 100% + repoze.bfg.functional 14 14 100% + repoze.bfg.includes 0 0 100% + repoze.bfg.interfaces 67 67 100% + repoze.bfg.location 42 42 100% + repoze.bfg.log 9 9 100% + repoze.bfg.lru 75 75 100% + repoze.bfg.path 12 12 100% + repoze.bfg.push 14 14 100% + repoze.bfg.registry 65 65 100% + repoze.bfg.request 25 25 100% + repoze.bfg.router 154 154 100% + repoze.bfg.security 150 150 100% + repoze.bfg.settings 24 24 100% + repoze.bfg.template 6 6 100% + repoze.bfg.templating 17 17 100% + repoze.bfg.testing 213 213 100% + repoze.bfg.tests 0 0 100% + repoze.bfg.tests.fixtureapp 0 0 100% + repoze.bfg.tests.fixtureapp.models 3 3 100% + repoze.bfg.tests.fixtureapp.views 4 4 100% + repoze.bfg.tests.grokkedapp 5 5 100% + repoze.bfg.tests.routesapp 0 0 100% + repoze.bfg.tests.routesapp.models 3 3 100% + repoze.bfg.tests.routesapp.views 4 4 100% + repoze.bfg.tests.test_chameleon_text 172 172 100% + repoze.bfg.tests.test_chameleon_zpt 161 161 100% + repoze.bfg.tests.test_events 59 59 100% + repoze.bfg.tests.test_integration 127 127 100% + repoze.bfg.tests.test_location 83 83 100% + repoze.bfg.tests.test_log 11 11 100% + repoze.bfg.tests.test_lru 74 74 100% + repoze.bfg.tests.test_push 29 29 100% + repoze.bfg.tests.test_registry 112 112 100% + repoze.bfg.tests.test_request 31 31 100% + repoze.bfg.tests.test_router 697 697 100% + repoze.bfg.tests.test_security 464 464 100% + repoze.bfg.tests.test_settings 83 83 100% + repoze.bfg.tests.test_template 73 73 100% + repoze.bfg.tests.test_templating 45 45 100% + repoze.bfg.tests.test_testing 379 379 100% + repoze.bfg.tests.test_traversal 616 616 100% + repoze.bfg.tests.test_url 126 126 100% + repoze.bfg.tests.test_urldispatch 338 338 100% + repoze.bfg.tests.test_view 418 418 100% + repoze.bfg.tests.test_wsgi 164 164 100% + repoze.bfg.tests.test_zcml 620 620 100% + repoze.bfg.traversal 215 215 100% + repoze.bfg.url 43 43 100% + repoze.bfg.urldispatch 157 157 100% + repoze.bfg.view 76 76 100% + repoze.bfg.wsgi 43 43 100% + repoze.bfg.zcml 246 246 100% + -------------------------------------------------------------------- + TOTAL 6678 6678 100% + ---------------------------------------------------------------------- + Ran 384 tests in 10.025s + + OK + diff --git a/docs/narr/project.rst b/docs/narr/project.rst index d18cfb7fd..66ce467f9 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -342,8 +342,8 @@ your application by requiring more settings in this section. The ``reload_templates`` setting in the ``[app:main]`` section is a :mod:`repoze.bfg`-specific setting which is passed into the framework. -If it exists, and is ``true``, :term:`Chameleon` and XSLT template -changes will not require an application restart to be detected. See +If it exists, and is ``true``, :term:`Chameleon` template changes will +not require an application restart to be detected. See :ref:`reload_templates_section` for more information. .. warning:: The ``reload_templates`` option should be turned off for diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index f1839cfed..985e1e237 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -17,14 +17,21 @@ complies largely with the `Zope Page Template `_ template specification and is significantly faster. -.. note:: :mod:`repoze.bfg` can also allow for the use of Genshi-style - templates via the ``chameleon.genshi`` package, support for which - is built-in to :mod:`repoze.bfg`. The :mod:`repoze.bfg` API - functions for getting and rendering Chameleon Genshi-style - templates mirrors the Chameleon ZPT-style API completely; only the - template files themselves must differ. See :ref:`template_module` - for more information about using Genshi-style templates within - :mod:`repoze.bfg`. +.. note:: The language definition documentation for Chameleon + ZPT-style templates is available from `the Chameleon website + `_. + +.. note:: As of version 0.8.0, :mod:`repoze.bfg` no longer supports + XSL templates "out of the box". The :mod:`repoze.bfg.xslt` package + is an add-on which provides XSL template bindings. + +.. note:: As of version 0.8.0, :mod:`repoze.bfg` no longer supports + Genshi-style Chameleon bindings "out of the box". The + :mod:`repoze.bfg.chameleon_genshi` package is an add-on which + provides Chameleon Genshi-style template support. + +.. note:: Jinja2 template bindings are available for :mod:`repoze.bfg` + in the :mod:`repoze.bfg.jinja2` package. Given that there is a :term:`chameleon.zpt` template named ``foo.pt`` in a directory in your application named ``templates``, @@ -118,50 +125,13 @@ And ``templates/mytemplate.pt`` might look like so: - + Chris - -Templating with XSLT ------------------------- - -:mod:`repoze.bfg` also supports XSLT as an optional templating -language. Like ZPT, an XSLT template is loaded once and re-used -between requests. - -Given a template ``foo.xsl`` in the templates directory, you can render -an XSLT as follows: - -.. code-block:: python - :linenos: - - from repoze.bfg.xslt import render_transform_to_response - from lxml import etree - node = etree.Element("root") - return render_transform_to_response('templates/foo.xsl', node) - -As shown, the second argument to ``render_transform_to_response`` is -the element (and children) that you want as the top of the data for -the XSLT. - -You can also pass XSLT parameters in as keyword arguments: - -.. code-block:: python - :linenos: - - from repoze.bfg.xslt import render_transform_to_response - from lxml import etree - node = etree.Element("root") - value1 = "'app1'" - return render_transform_to_response('templates/foo.xsl', node, param1=value1) - -This would then assign 'app1' as the value of an ```` parameter in the XSLT template. - .. _reload_templates_section: Automatically Reloading Templates @@ -241,3 +211,21 @@ installed, here's an example of using Mako from within a Note that if you use third-party templating languages, the auto-template-reload strategy explained in :ref:`reload_templates_section` will not be available. + +Available Add-On Template System Bindings +----------------------------------------- + +:mod:`repoze.bfg.xslt` is an add-on which provides XSL template +bindings. It lives in the Repoze Subversion repository at +`http://svn.repoze.org/repoze.bfg.xslt +`_. + +:mod:`repoze.bfg.chameleon_genshi` package is an add-on which provides +Chameleon Genshi-style template support. It lives in the Repoze +Subversion repository at `http://svn.repoze.org/repoze.bfg.chameleon_genshi +`_. + +Jinja2 template bindings are available for :mod:`repoze.bfg` in the +:mod:`repoze.bfg.jinja2` package. It lives in the Repoze Subversion +repository at `http://svn.repoze.org/repoze.bfg.jinja2 +`_. -- cgit v1.2.3