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 2013/08/14 20:56:40 UTC
[10/25] git commit: [#4818] add documentation for extensions
[#4818] add documentation for extensions
Project: http://git-wip-us.apache.org/repos/asf/incubator-allura/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-allura/commit/df942cb2
Tree: http://git-wip-us.apache.org/repos/asf/incubator-allura/tree/df942cb2
Diff: http://git-wip-us.apache.org/repos/asf/incubator-allura/diff/df942cb2
Branch: refs/heads/cj/6464
Commit: df942cb262f9b541dd6235420e3a39c1398e6693
Parents: 5f836ba
Author: Dave Brondsema <db...@slashdotmedia.com>
Authored: Fri Aug 9 19:41:28 2013 +0000
Committer: Tim Van Steenburgh <tv...@gmail.com>
Committed: Wed Aug 14 13:12:13 2013 +0000
----------------------------------------------------------------------
Allura/allura/app.py | 2 +-
Allura/allura/lib/plugin.py | 10 +++---
Allura/docs/api/app.rst | 13 +-------
Allura/docs/api/lib/plugin.rst | 24 ++++++++++++++
Allura/docs/api/lib/spam.rst | 24 ++++++++++++++
Allura/docs/extending.rst | 55 +++++++++++++++++++++++++++++++++
Allura/docs/guides/message_bus.rst | 4 ++-
Allura/docs/index.rst | 3 +-
8 files changed, 115 insertions(+), 20 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/df942cb2/Allura/allura/app.py
----------------------------------------------------------------------
diff --git a/Allura/allura/app.py b/Allura/allura/app.py
index c1d2517..5ac11f2 100644
--- a/Allura/allura/app.py
+++ b/Allura/allura/app.py
@@ -164,7 +164,7 @@ class Application(object):
The base Allura pluggable application
After extending this, expose the app by adding an entry point in your
- setup.py:
+ setup.py::
[allura]
myapp = foo.bar.baz:MyAppClass
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/df942cb2/Allura/allura/lib/plugin.py
----------------------------------------------------------------------
diff --git a/Allura/allura/lib/plugin.py b/Allura/allura/lib/plugin.py
index f972c26..f600363 100644
--- a/Allura/allura/lib/plugin.py
+++ b/Allura/allura/lib/plugin.py
@@ -56,12 +56,12 @@ class AuthenticationProvider(object):
'''
An interface to provide authentication services for Allura.
- To use a new provider, expose an entry point in setup.py:
+ To use a new provider, expose an entry point in setup.py::
[allura.auth]
myprovider = foo.bar:MyAuthProvider
- Then in your .ini file, set auth.method=myprovider
+ Then in your .ini file, set ``auth.method=myprovider``
'''
def __init__(self, request):
@@ -346,7 +346,7 @@ class ProjectRegistrationProvider(object):
and the default. Extend this class with your own if you need to add more
functionality.
- To use a new provider, expose an entry point in setup.py:
+ To use a new provider, expose an entry point in setup.py::
[allura.project_registration]
myprovider = foo.bar:MyAuthProvider
@@ -625,7 +625,7 @@ class ThemeProvider(object):
and the default. Extend this class with your own if you need to add more
functionality.
- To use a new provider, expose an entry point in setup.py:
+ To use a new provider, expose an entry point in setup.py::
[allura.theme]
myprovider = foo.bar:MyThemeProvider
@@ -855,7 +855,7 @@ class UserPreferencesProvider(object):
'''
An interface for user preferences, like display_name and email_address
- To use a new provider, expose an entry point in setup.py:
+ To use a new provider, expose an entry point in setup.py::
[allura.user_prefs]
myprefs = foo.bar:MyUserPrefProvider
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/df942cb2/Allura/docs/api/app.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/api/app.rst b/Allura/docs/api/app.rst
index 491d0b4..f99a0c2 100644
--- a/Allura/docs/api/app.rst
+++ b/Allura/docs/api/app.rst
@@ -22,15 +22,4 @@
.. automodule:: allura.app
- .. autoclass:: Application
- :members:
-
- .. autoclass:: ConfigOption
- :members:
-
- .. autoclass:: DefaultAdminController
- :members:
-
- .. autoclass:: SitemapEntry
- :members:
-
+ :members:
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/df942cb2/Allura/docs/api/lib/plugin.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/api/lib/plugin.rst b/Allura/docs/api/lib/plugin.rst
new file mode 100644
index 0000000..77e619b
--- /dev/null
+++ b/Allura/docs/api/lib/plugin.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.
+
+.. _plugin_module:
+
+:mod:`allura.lib.plugin`
+-------------------------------------
+
+.. automodule:: allura.lib.plugin
+ :members:
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/df942cb2/Allura/docs/api/lib/spam.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/api/lib/spam.rst b/Allura/docs/api/lib/spam.rst
new file mode 100644
index 0000000..b9558a3
--- /dev/null
+++ b/Allura/docs/api/lib/spam.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.
+
+.. _spam_module:
+
+:mod:`allura.lib.spam`
+-------------------------------------
+
+.. automodule:: allura.lib.spam
+ :members:
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/df942cb2/Allura/docs/extending.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/extending.rst b/Allura/docs/extending.rst
new file mode 100644
index 0000000..a430202
--- /dev/null
+++ b/Allura/docs/extending.rst
@@ -0,0 +1,55 @@
+.. 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.
+
+Extending Allura with 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
+available immediately. Others, such as authentication providers or themes, need
+to be specified in your ``.ini`` file, since you may only have one enabled at a time.
+
+The available extension points for Allura are:
+
+* :class:`allura.app.Application` (aka tool) and :class:`allura.app.Artifact`
+* :class:`allura.lib.plugin.ThemeProvider`
+* :class:`allura.lib.plugin.ProjectRegistrationProvider`
+* :class:`allura.lib.plugin.AuthenticationProvider`
+* :class:`allura.lib.plugin.UserPreferencesProvider`
+* :class:`allura.lib.plugin.AdminExtension`
+* :class:`allura.lib.spam.SpamFilter`
+* ``site_stats`` in the root API data. Docs in :class:`allura.controllers.rest.RestController`
+* :mod:`allura.lib.package_path_loader` (for overriding templates)
+
+A listing of available 3rd-party extensions is at https://sourceforge.net/p/allura/wiki/Extensions/
+
+Other entry points are used to provider ``paster`` commands and ``easy_widget`` configuration.
+
+
+Event Handlers
+==============
+
+Another way to extend Allura is set up event handlers to respond to Allura events.
+There is documentation and examples at :ref:`events`.
+
+The events that allura publishes are:
+
+* project_created
+* project_updated
+* repo_cloned
+* repo_refreshed
+* repo_clone_task_failed
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/df942cb2/Allura/docs/guides/message_bus.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/guides/message_bus.rst b/Allura/docs/guides/message_bus.rst
index f8285e1..11067c9 100644
--- a/Allura/docs/guides/message_bus.rst
+++ b/Allura/docs/guides/message_bus.rst
@@ -61,6 +61,8 @@ well::
commit()
+.. _events:
+
Events
-------------------
@@ -82,7 +84,7 @@ Under the covers, this is scheduling an `event` task that calls all the handlers
for a particular named event. Note that you can pass arguments (\*args, and
\*\*kwargs) to event handlers just like you do to tasks, with the exception that
the topic name (above, this would be 'project_updated') is always the first
-parameter passed to the event handler.
+parameter passed to the event handler.
Running the Task Daemon
----------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/df942cb2/Allura/docs/index.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/index.rst b/Allura/docs/index.rst
index 56b1b52..877b98d 100644
--- a/Allura/docs/index.rst
+++ b/Allura/docs/index.rst
@@ -57,12 +57,13 @@ Inside the Platform Components
guides/message_bus
guides/email
guides/permissions
+ extending
API Documentation
==================
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
:glob:
api/*