incubator-allura-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From john...@apache.org
Subject git commit: [#7002] Improved documentation of user profile sections extension point
Date Wed, 22 Jan 2014 23:04:53 GMT
Updated Branches:
  refs/heads/cj/7002 a2bc2dd64 -> fac2768ef


[#7002] Improved documentation of user profile sections extension point

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/fac2768e
Tree: http://git-wip-us.apache.org/repos/asf/incubator-allura/tree/fac2768e
Diff: http://git-wip-us.apache.org/repos/asf/incubator-allura/diff/fac2768e

Branch: refs/heads/cj/7002
Commit: fac2768efe69a3c1b75cc54cf41cec8a4ba4c489
Parents: a2bc2dd
Author: Cory Johns <cjohns@slashdotmedia.com>
Authored: Wed Jan 22 23:04:22 2014 +0000
Committer: Cory Johns <cjohns@slashdotmedia.com>
Committed: Wed Jan 22 23:04:32 2014 +0000

----------------------------------------------------------------------
 Allura/allura/ext/user_profile/user_main.py | 43 +++++++++++++++++++++++-
 Allura/docs/api/ext.rst                     | 28 +++++++++++++++
 Allura/docs/api/ext/user_profile.rst        | 24 +++++++++++++
 Allura/docs/extending.rst                   |  5 +--
 ForgeActivity/forgeactivity/main.py         |  5 ++-
 5 files changed, 99 insertions(+), 6 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/fac2768e/Allura/allura/ext/user_profile/user_main.py
----------------------------------------------------------------------
diff --git a/Allura/allura/ext/user_profile/user_main.py b/Allura/allura/ext/user_profile/user_main.py
index 31e4bf0..a9758e1 100644
--- a/Allura/allura/ext/user_profile/user_main.py
+++ b/Allura/allura/ext/user_profile/user_main.py
@@ -47,6 +47,10 @@ class F(object):
 
 
 class UserProfileApp(Application):
+    """
+    This is the Profile tool, which is automatically installed as
+    the default (first) tool on any user project.
+    """
     __version__ = version.__version__
     tool_label = 'Profile'
     max_instances = 0
@@ -90,7 +94,8 @@ class UserProfileApp(Application):
     @property
     def profile_sections(self):
         """
-        Loads and caches user profile sections.
+        Loads and caches user profile sections from the entry-point
+        group ``[allura.user_profile.sections]``.
 
         Profile sections are loaded unless disabled (see
         `allura.lib.helpers.iter_entry_points`) and are sorted according
@@ -202,15 +207,51 @@ class UserProfileController(BaseController, FeedController):
 
 
 class ProfileSectionBase(object):
+    """
+    This is the base class for sections on the Profile tool.
+
+    .. py:attribute:: template
+
+       A resource string pointing to the template for this section.  E.g.::
+
+           template = "allura.ext.user_profile:templates/projects.html"
+
+    Sections must be pointed to by an entry-point in the group
+    ``[allura.user_profile.sections]``.
+    """
     template = ''
 
+    def __init__(self, user, project):
+        """
+        Creates a section for the given :param:`user` and user
+        :param:`project`.  Stores the values as attributes of
+        the same name.
+        """
+        self.user = user
+        self.project = project
+
     def check_display(self):
+        """
+        Should return True if the section should be displayed.
+        """
         return True
 
     def prepare_context(self, context):
+        """
+        Should be overridden to add any values to the template context prior
+        to display.
+        """
         return context
 
     def display(self, *a, **kw):
+        """
+        Renders the section using the context from :meth:`prepare_context`
+        and the :attr:`template`, if :meth:`check_display` returns True.
+
+        If overridden or this base class is not used, this method should
+        return either plain text (which will be escaped) or a `jinja2.Markup`
+        instance.
+        """
         if not self.check_display():
             return ''
         tmpl = g.jinja2_env.get_template(self.template)

http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/fac2768e/Allura/docs/api/ext.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/api/ext.rst b/Allura/docs/api/ext.rst
new file mode 100644
index 0000000..9f1580b
--- /dev/null
+++ b/Allura/docs/api/ext.rst
@@ -0,0 +1,28 @@
+..     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.
+
+.. _ext_module:
+
+:mod:`allura.ext`
+--------------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   ext/*
+

http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/fac2768e/Allura/docs/api/ext/user_profile.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/api/ext/user_profile.rst b/Allura/docs/api/ext/user_profile.rst
new file mode 100644
index 0000000..f247693
--- /dev/null
+++ b/Allura/docs/api/ext/user_profile.rst
@@ -0,0 +1,24 @@
+..     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.
+
+.. _user_profile_module:
+
+:mod:`allura.ext.user_profile`
+-------------------------------------
+
+.. automodule:: allura.ext.user_profile.user_main
+    :members:

http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/fac2768e/Allura/docs/extending.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/extending.rst b/Allura/docs/extending.rst
index c39d572..9758f55 100644
--- a/Allura/docs/extending.rst
+++ b/Allura/docs/extending.rst
@@ -15,8 +15,8 @@
        specific language governing permissions and limitations
        under the License.
 
-Extending Allura with Entry Points
-===================================
+Extension APIs and Entry Points
+===============================
 
 There are many extension points to extending Allura.  They all make themselves
 known to Allura via python entry points defined in ``setup.py``.  Many are then
@@ -35,6 +35,7 @@ The available extension points for Allura are:
 * ``site_stats`` in the root API data.  Docs in :class:`allura.controllers.rest.RestController`
 * :mod:`allura.lib.package_path_loader` (for overriding templates)
 * ``[allura.timers]`` functions which return a list or single :class:`timermiddleware.Timer`
which will be included in stats.log timings
+* :mod:`allura.ext.user_profile`
 
 A listing of available 3rd-party extensions is at https://forge-allura.apache.org/p/allura/wiki/Extensions/
 

http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/fac2768e/ForgeActivity/forgeactivity/main.py
----------------------------------------------------------------------
diff --git a/ForgeActivity/forgeactivity/main.py b/ForgeActivity/forgeactivity/main.py
index a86d00f..da81307 100644
--- a/ForgeActivity/forgeactivity/main.py
+++ b/ForgeActivity/forgeactivity/main.py
@@ -206,9 +206,8 @@ class ForgeActivityRestController(BaseController):
 class ForgeActivityProfileSection(ProfileSectionBase):
     template = 'forgeactivity:templates/widgets/profile_section.html'
 
-    def __init__(self, user, project):
-        self.user = user
-        self.project = project
+    def __init__(self, *a, **kw):
+        super(ForgeActivityProfileSection, self).__init__(*a, **kw)
         self.activity_app = self.project.app_instance('activity')
 
     def check_display(self):


Mime
View raw message