You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@allura.apache.org by jo...@apache.org on 2014/01/23 18:30:01 UTC
[19/28] git commit: [#7002] Improved documentation of user profile
sections extension point
[#7002] Improved documentation of user profile sections extension point
Signed-off-by: Cory Johns <cj...@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/88b25003
Tree: http://git-wip-us.apache.org/repos/asf/incubator-allura/tree/88b25003
Diff: http://git-wip-us.apache.org/repos/asf/incubator-allura/diff/88b25003
Branch: refs/heads/cj/4257
Commit: 88b250031a3b93c0568d7a819c5c38e93189aaf7
Parents: 6c2cb1a
Author: Cory Johns <cj...@slashdotmedia.com>
Authored: Wed Jan 22 23:04:22 2014 +0000
Committer: Cory Johns <cj...@slashdotmedia.com>
Committed: Wed Jan 22 23:13:31 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/88b25003/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/88b25003/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/88b25003/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/88b25003/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/88b25003/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):