You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@allura.apache.org by tv...@apache.org on 2014/01/02 21:23:24 UTC
[10/14] git commit: [#5424] reorganize doc TOC, remove old stuff,
add links to external documentation
[#5424] reorganize doc TOC, remove old stuff, add links to external documentation
Project: http://git-wip-us.apache.org/repos/asf/incubator-allura/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-allura/commit/ea26b2a8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-allura/tree/ea26b2a8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-allura/diff/ea26b2a8
Branch: refs/heads/master
Commit: ea26b2a8a1f3d82f5a3478268eb1ab9f821bad1b
Parents: 6221342
Author: Dave Brondsema <db...@slashdotmedia.com>
Authored: Tue Nov 19 18:56:12 2013 -0500
Committer: Tim Van Steenburgh <tv...@gmail.com>
Committed: Thu Jan 2 20:22:34 2014 +0000
----------------------------------------------------------------------
Allura/docs/administration.rst | 15 ++++++
Allura/docs/index.rst | 29 ++++-------
Allura/docs/tutorials/tool.rst | 58 +++++++++++++++++++++
Allura/docs/tutorials/wiki-tool.rst | 87 --------------------------------
4 files changed, 84 insertions(+), 105 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/ea26b2a8/Allura/docs/administration.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/administration.rst b/Allura/docs/administration.rst
index 19c2e53..303d778 100644
--- a/Allura/docs/administration.rst
+++ b/Allura/docs/administration.rst
@@ -93,3 +93,18 @@ user closes it manually. An `impressions` value of 0 will show the notification
indefinitely (until closed). The notification content can contain HTML. Only the
most recent notification will be shown, unless it has `active:false`, in which case
no notification will be shown.
+
+
+Using Projects and Tools
+------------------------
+
+We currently don't have any further documentation for basic operations of managing
+users, projects, and tools on Allura. However, SourceForge has help docs that cover
+these functions https://sourceforge.net/p/forge/documentation/Docs%20Home/ Note
+that this documentation also covers some SourceForge features that are not part of Allura.
+
+
+Public API Documentation
+------------------------
+
+Allura's web api is currently documented at https://sourceforge.net/p/forge/documentation/Allura%20API/
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/ea26b2a8/Allura/docs/index.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/index.rst b/Allura/docs/index.rst
index ebbd0bf..81c4426 100644
--- a/Allura/docs/index.rst
+++ b/Allura/docs/index.rst
@@ -20,7 +20,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Introducing the *Allura* Platform:
+Introduction
=====================================================================
.. toctree::
@@ -28,7 +28,7 @@ Introducing the *Allura* Platform:
intro
-Getting Started
+Running Allura
=====================================================================
.. toctree::
@@ -36,29 +36,29 @@ Getting Started
installation
administration
- platform_tour
scm_host
migration
-Writing a Allura based app
+Developing Allura
=====================================================================
.. toctree::
:maxdepth: 3
- tutorials/wiki-tool
+ platform
+ platform_tour
+ guides/message_bus
+ guides/email
+ guides/permissions
-Inside the Platform Components
+Extending Allura
=====================================================================
.. toctree::
:maxdepth: 3
- platform
- guides/message_bus
- guides/email
- guides/permissions
extending
+ tutorials/tool
API Documentation
==================
@@ -69,19 +69,12 @@ API Documentation
api/*
-Frequently Asked Questions
+Background Info
=====================================================================
.. toctree::
:maxdepth: 1
faq
-
-Project References
-=====================================================================
-
-.. toctree::
- :maxdepth: 1
-
online
Indices and tables
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/ea26b2a8/Allura/docs/tutorials/tool.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/tutorials/tool.rst b/Allura/docs/tutorials/tool.rst
new file mode 100644
index 0000000..2ab768d
--- /dev/null
+++ b/Allura/docs/tutorials/tool.rst
@@ -0,0 +1,58 @@
+.. 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.
+
+Creating your first Allura Tool
+=====================================================================
+
+Tim Van Steenburgh has written a `series of posts guiding you through
+writing an Allura tool <https://sourceforge.net/u/vansteenburgh/allura-plugin-development/>`_.
+There is also a `companion git repo <https://sourceforge.net/u/vansteenburgh/plugin-tutorial/ci/master/tree/>`_.
+
+
+Testing your Tool
+===========================
+
+Testing the controllers and models of an Allura tool is fairly
+straightforward. Generally, you should follow the example of tests in the
+`allura/tests/functional` directory for controller tests and
+`allura.tests.model` for model tests. For functional tests, the Allura platform
+provides a convenient "test harness" :class:`allura.controllers.test.TestController` controller
+class which is used as the application root for the
+:class:`allura.tests.TestController` class.
+
+In order to test your new tool controllers, you simply need to use the `self.app.get()`
+and `self.app.post()` methods of your test controller. The test harness makes
+all the tools available in the system available under the URL /*entry point
+name*/. So to test the :mod:`allura.ext.project_home` tool, for instance, we
+need only write the following::
+
+ from allura.tests import TestController
+
+ class TestProjectHome(TestController):
+
+ def test_home(self):
+ r = self.app.get('/home/')
+
+Whenever you use the :class:`allura.tests.TestController` app property, the
+test harness sets up the context so that `c.project` is always the
+`projects/test` project and whichever tool name you request is mounted at its
+entry point (so the Wiki tool will be mounted at /Wiki/). `c.user` is always
+set to the `test-admin` user to avoid authentication issues.
+
+The framework used to generate the WSGI environment for testing your tools is
+provided by the `WebTest <http://pythonpaste.org/webtest/>`_ module, where you can
+find further documentation for the `.get()` and `.post()` methods.
http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/ea26b2a8/Allura/docs/tutorials/wiki-tool.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/tutorials/wiki-tool.rst b/Allura/docs/tutorials/wiki-tool.rst
deleted file mode 100644
index 1e5d4ff..0000000
--- a/Allura/docs/tutorials/wiki-tool.rst
+++ /dev/null
@@ -1,87 +0,0 @@
-.. 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.
-
-Creating your first Allura Tool
-=====================================================================
-
-Adding your Allura Tool to a Allura Install
-=====================================================================
-
-Writing a Wiki Tool Part 1: Pages
-=====================================================================
-
-Writing a wiki Tool Part 2: Links
-=====================================================================
-
-Writing a wiki Tool Part 3: Revisions
-=====================================================================
-
-Testing your Tool
-===========================
-
-Testing the controllers and models of an Allura tool is fairly
-straightforward. Generally, you should follow the example of tests in the
-`allura/tests/functional` directory for controller tests and
-`allura.tests.model` for model tests. For functional tests, the Allura platform
-provides a convenient "test harness" :class:`allura.controllers.test.TestController` controller
-class which is used as the application root for the
-:class:`allura.tests.TestController` class.
-
-In order to test your new tool controllers, you simply need to use the `self.app.get()`
-and `self.app.post()` methods of your test controller. The test harness makes
-all the tools available in the system available under the URL /*entry point
-name*/. So to test the :mod:`allura.ext.project_home` tool, for instance, we
-need only write the following::
-
- from allura.tests import TestController
-
- class TestProjectHome(TestController):
-
- def test_home(self):
- r = self.app.get('/home/')
-
-Whenever you use the :class:`allura.tests.TestController` app property, the
-test harness sets up the context so that `c.project` is always the
-`projects/test` project and whichever tool name you request is mounted at its
-entry point (so the Wiki tool will be mounted at /Wiki/). `c.user` is always
-set to the `test-admin` user to avoid authentication issues.
-
-The framework used to generate the WSGI environment for testing your tools is
-provided by the `WebTest <http://pythonpaste.org/webtest/>`_ module, where you can
-find further documentation for the `.get()` and `.post()` methods.
-
-Testing Allura models is also straightforward, though it usually requires
-setting the pylons context object `c` before your test. An example of this
-technique follows::
-
- import mock
- from pylons import tmpl_context as c, app_globals as g
-
- from allura.lib.app_globals import Globals
- from allura import model as M
-
- def setUp():
- g._push_object(Globals())
- c._push_object(mock.Mock())
- g.set_project('projects/test')
- g.set_app('hello')
- c.user = M.User.query.get(username='test-admin')
-
-Testing the tasks and events is similar to testing models. Generally, you will
-simply want to call your `@task` and `@event_handler` methods directly rather
-than setting up a full mocking infrastructure, though it is possible to use the
-MonQTask model in the allura model if you wish to do more functional/integration testing.