incubator-allura-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From brond...@apache.org
Subject [4/8] git commit: [#4818] add documentation for extensions
Date Tue, 13 Aug 2013 20:39:08 GMT
[#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/8f432d0c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-allura/tree/8f432d0c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-allura/diff/8f432d0c

Branch: refs/heads/db/6482
Commit: 8f432d0caadff58cb9207079e06448633758a238
Parents: 701f990
Author: Dave Brondsema <dbrondsema@slashdotmedia.com>
Authored: Fri Aug 9 19:41:28 2013 +0000
Committer: Dave Brondsema <dbrondsema@slashdotmedia.com>
Committed: Tue Aug 13 20:38:42 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/8f432d0c/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/8f432d0c/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/8f432d0c/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/8f432d0c/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/8f432d0c/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/8f432d0c/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/8f432d0c/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/8f432d0c/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/*


Mime
View raw message