incubator-allura-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From john...@apache.org
Subject [09/12] git commit: [#6325] Touched up and tied in documentation for PPL
Date Fri, 07 Jun 2013 17:20:08 GMT
[#6325] Touched up and tied in documentation for PPL

Signed-off-by: Cory Johns <cjohns@slashdotmedia.com>


Project: http://git-wip-us.apache.org/repos/asf/incubator-allura/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-allura/commit/445b6409
Tree: http://git-wip-us.apache.org/repos/asf/incubator-allura/tree/445b6409
Diff: http://git-wip-us.apache.org/repos/asf/incubator-allura/diff/445b6409

Branch: refs/heads/cj/6314
Commit: 445b6409ec581e99369cb3fe13c3088eb045c3a2
Parents: f67aaa2
Author: Cory Johns <cjohns@slashdotmedia.com>
Authored: Tue Jun 4 22:16:46 2013 +0000
Committer: Cory Johns <cjohns@slashdotmedia.com>
Committed: Tue Jun 4 22:16:46 2013 +0000

----------------------------------------------------------------------
 Allura/allura/lib/package_path_loader.py    |   89 ++++++++++++----------
 Allura/docs/api/lib.rst                     |   27 +++++++
 Allura/docs/api/lib/package_path_loader.rst |   26 ++++++
 3 files changed, 101 insertions(+), 41 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/445b6409/Allura/allura/lib/package_path_loader.py
----------------------------------------------------------------------
diff --git a/Allura/allura/lib/package_path_loader.py b/Allura/allura/lib/package_path_loader.py
index 0efde59..e4be82e 100644
--- a/Allura/allura/lib/package_path_loader.py
+++ b/Allura/allura/lib/package_path_loader.py
@@ -14,38 +14,45 @@
 #       KIND, either express or implied.  See the License for the
 #       specific language governing permissions and limitations
 #       under the License.
-'''
+"""
 A Jinja template loader which allows for:
- - dotted-notation package loading
- - search-path-based overriding of same
 
-## Dotted notation
+- dotted-notation package loading
+- search-path-based overriding of same
+
+Dotted notation
+---------------
+
 - Allow a Tool implementer to use a dotted-notation module name
-  (as occuring in the PYTONPATH), then the given path within the
-  module:
+  (as occuring in the ``PYTHONPATH``), then the given path within the
+  module::
 
-        @expose('jinja:module.name:path/within/module.html>')
+        @expose('jinja:<module.name>:<path/within/module.html>')
 
-  e.g.
+  e.g.::
 
         @expose('jinja:allura:templates/repo/file.html')
 
-## Overriding dotted notation
+Overriding dotted notation
+--------------------------
+
 Allow a Tool implementer to override the theme baseline (or any
 other Tool's) templates. This can be lighter-weight than subclassing
-allura.plugin.ThemeProvider, plus will allow for more fine-grained
+:ref:`allura.plugin.ThemeProvider`, plus will allow for more fine-grained
 changes.
 
-This will also override `extends` and `import` Jinja tags.
+This will also override ``extends`` and ``import`` Jinja tags.
 
 This approach uses a:
 
-- setup.py entry point to a class with...
-- _magic_ files and...
+- ``setup.py`` entry point to a class with...
+- *magic* files and...
 - (optionally) a class property to specify ordering
 
-### File Structure for Overriding dotted notation
-For the examples, assume the following directory structure:
+File Structure for Overriding dotted notation
+=============================================
+
+For the examples, assume the following directory structure::
 
     NewTool/
     |- setup.py                     <- entry point specified here
@@ -60,26 +67,28 @@ For the examples, assume the following directory structure:
                    |- file.html     <- actual template
 
 To override the above example, a Tool implementer would
-add the following line to their Tool's setup.py (assuming usage in Allura,
-with the default app_cfg):
+add the following line to their Tool's ``setup.py`` (assuming usage in Allura,
+with the default ``app_cfg``)::
 
     [allura.theme.override]
     newtool = newtool.app:NewToolApp
 
 Then, in the neighbor path (see below) for the file containing the
-Tool class, add the following path/file:
+Tool class, add the following path/file::
 
     override/allura/templates/repo/file.html
 
 The template will be overridden. Note that after changing
-setup.py, it would be required to re-initialize with setuptools:
+``setup.py``, it would be required to re-initialize with setuptools::
 
     python setup.py develop
 
-###  Specifying search path order with template_path_rules
+Specifying search path order with template_path_rules
+=====================================================
+
 If a highly specific ordering is required, such as if multiple Tools
 are trying to override the same template, the entry point target
-class can also contain a class property template_path_rules:
+class can also contain a class property template_path_rules::
 
     class NewToolApp(Application):
         template_path_rules = [
@@ -87,26 +96,29 @@ class can also contain a class property template_path_rules:
         ]
 
 Each rule specifies a postioner and an entry point or "signpost".
-If no rule is provided, the default is ['>', 'allura'].
+If no rule is provided, the default is ``['>', 'allura']``.
 
 The "signposts" are:
 
-- site-theme
-- allura (you probably shouldn't do this)
-- project-theme NOT IMPLEMENTED
-- tool-theme NOT IMPLEMENTED
+- Any other app's override entry point name
+- ``site-theme``
+- ``allura`` (you probably shouldn't do this)
+- ``project-theme`` **NOT IMPLEMENTED**
+- ``tool-theme`` **NOT IMPLEMENTED**
 
 The positioners are:
-- >
-    - This overrider will be found BEFORE the specified entry point
-- <
-    - This overrider will be found AFTER the specified entry point... not
-      exectly sure why you would use this.
-- =
-    - This will replace one of the "signpost" entry points... if multiple
-      entry points try to do this, the result is undefined.
-      TODO: Support multiple partial themes
-'''
+
+    >
+        This overrider will be found BEFORE the specified entry point
+    <
+        This overrider will be found AFTER the specified entry point
+    =
+        This will replace one of the "signpost" entry points (if multiple apps
+        try to do this for the same signpost, the result is undefined)
+
+**TODO:** Support multiple partial themes
+"""
+
 import pkg_resources
 import os
 from collections import defaultdict
@@ -118,11 +130,6 @@ from allura.lib.helpers import topological_sort
 
 
 class PackagePathLoader(jinja2.BaseLoader):
-    '''
-    Implements the following extensions to the BaseLoader for locating
-    templates: dotted-notation module-based template loading, and overriding
-    the same with other Tools.
-    '''
     def __init__(self, override_entrypoint='allura.theme.override',
                 default_paths=None,
                 override_root='override',

http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/445b6409/Allura/docs/api/lib.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/api/lib.rst b/Allura/docs/api/lib.rst
new file mode 100644
index 0000000..1125fbb
--- /dev/null
+++ b/Allura/docs/api/lib.rst
@@ -0,0 +1,27 @@
+..     Licensed to the Apache Software Foundation (ASF) under one
+       or more contributor license agreements.  See the NOTICE file
+       distributed with this work for additional information
+       regarding copyright ownership.  The ASF licenses this file
+       to you under the Apache License, Version 2.0 (the
+       "License"); you may not use this file except in compliance
+       with the License.  You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+       Unless required by applicable law or agreed to in writing,
+       software distributed under the License is distributed on an
+       "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+       KIND, either express or implied.  See the License for the
+       specific language governing permissions and limitations
+       under the License.
+
+.. _lib_module:
+
+:mod:`allura.lib`
+--------------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   lib/*

http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/445b6409/Allura/docs/api/lib/package_path_loader.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/api/lib/package_path_loader.rst b/Allura/docs/api/lib/package_path_loader.rst
new file mode 100644
index 0000000..0646699
--- /dev/null
+++ b/Allura/docs/api/lib/package_path_loader.rst
@@ -0,0 +1,26 @@
+..     Licensed to the Apache Software Foundation (ASF) under one
+       or more contributor license agreements.  See the NOTICE file
+       distributed with this work for additional information
+       regarding copyright ownership.  The ASF licenses this file
+       to you under the Apache License, Version 2.0 (the
+       "License"); you may not use this file except in compliance
+       with the License.  You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+       Unless required by applicable law or agreed to in writing,
+       software distributed under the License is distributed on an
+       "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+       KIND, either express or implied.  See the License for the
+       specific language governing permissions and limitations
+       under the License.
+
+.. _package_path_loader_module:
+
+:mod:`allura.lib.package_path_loader`
+--------------------------------
+
+.. automodule:: allura.lib.package_path_loader
+
+  .. autoclass:: PackagePathLoader
+      :members:


Mime
View raw message