You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@allura.apache.org by je...@apache.org on 2015/03/06 13:35:23 UTC
[16/26] allura git commit: [#7835] Restructured the docs and updated
the theme.
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/scm_host.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/scm_host.rst b/Allura/docs/scm_host.rst
deleted file mode 100644
index d3fe205..0000000
--- a/Allura/docs/scm_host.rst
+++ /dev/null
@@ -1,236 +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.
-
-.. _scm_hosting:
-
-Git and Subversion Hosting Installation
-=======================================
-
-Allura can manage and display Git and SVN repositories, but it doesn't
-automatically run the git and svn services for you. Here we'll describe how
-to set up standard git and svn services to work with Allura, so that you can
-checkout and commit code with those repositories. The instructions here assume
-an Ubuntu system, but should be similar on other systems.
-
-.. note::
-
- For developing with Allura or simple testing of Allura, you do not need to run
- these services. You can use local filesystem access to git and svn, which
- works with no additional configuration.
-
-Git
----
-
-We'll cover the basics to get you going. For additional options and details,
-see http://git-scm.com/docs/git-http-backend and http://git-scm.com/book/en/Git-on-the-Server
-and subsequent chapters.
-
-.. code-block:: bash
-
- sudo chmod 775 /srv/* # make sure apache can read the repo dirs
- sudo apt-get install apache2
- sudo a2enmod proxy rewrite
- sudo vi /etc/apache2/sites-available/default
-
-And add the following text within the :code:`<VirtualHost>` block:
-
-.. code-block:: apache
-
- SetEnv GIT_PROJECT_ROOT /srv/git
- SetEnv GIT_HTTP_EXPORT_ALL
- ProxyPass /git/ !
- ScriptAlias /git/ /usr/lib/git-core/git-http-backend/
-
- # no authentication required at all - for testing purposes
- SetEnv REMOTE_USER=git-allura
-
-Then exit vim (:kbd:`<esc> :wq`) and run:
-
-.. code-block:: shell-session
-
- sudo service apache2 reload
-
-To test that it's working, run: :command:`git ls-remote http://localhost/git/p/test/git/`
-(if using Vagrant, you may also use :code:`localhost:8088` from your host machine).
-If there is no output, that is fine (it's an empty repo).
-
-.. warning::
-
- This configuration has no authentication and is suitable for development only. See :ref:`below <auth_apache>` for auth config.
-
-Now you will want to change the :samp:`scm.host.{*}.git`
-settings in :file:`development.ini`, so that the proper commands are shown to your visitors
-when they browse the code repo web pages. The exact values to use will depend on the
-hostnames and port numbers you are using.
-
-Read-only `git://`
-^^^^^^^^^^^^^^^^^^
-If you want to run a separate readonly git service, using the git protocol instead of http,
-run: :program:`git daemon --reuseaddr --export-all --base-path=/srv/git /srv/git` It can
-be accessed at :code:`git://localhost/p/test/git`
-
-
-Subversion
-----------
-
-These instructions will cover the recommended easiest way to run Subversion with Allura.
-For an overview of other options, see http://svnbook.red-bean.com/en/1.8/svn.serverconfig.choosing.html
-and subsequent chapters.
-
-.. code-block:: bash
-
- sudo chown allura:allura /srv/svn # or other user, as needed (e.g. "vagrant")
-
- cat > /srv/svn/svnserve.conf <<EOF
- [general]
- realm = My Site SVN
- # no authentication required at all - for testing purposes
- anon-access = write
- EOF
-
- svnserve -d -r /srv/svn --log-file /tmp/svnserve.log --config-file /srv/svn/svnserve.conf
-
-Test by running: :command:`svn info svn://localhost/p/test/code/`. If you need to kill it,
-run :command:`killall svnserve` More info at http://svnbook.red-bean.com/en/1.8/svn.serverconfig.svnserve.html
-
-.. warning::
-
- This configuration has no authentication and is suitable for development only.
- (Maybe Allura could gain SASL support someday and use `svnserve with SASL <http://svnbook.red-bean.com/en/1.7/svn.serverconfig.svnserve.html#svn.serverconfig.svnserve.sasl>`_)
-
-Now you will want to change the :samp:`scm.host.{*}.svn`
-settings in :file:`development.ini`, so that the proper commands are shown to your visitors
-when they browse the code repo web pages.
-
-Alternate Setup with HTTP
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To use SVN over HTTP, you will need to patch and compile an Apache module, so
-that all svn repos can be dynamically served.
-
-.. warning::
-
- Not easy.
-
-.. code-block:: console
-
- sudo aptitude install libapache2-svn
-
-Test accessing http://localhost/ (`localhost:8088` if using Vagrant).
-
-Now we'll configure Apache to serve a single project's repositories and make sure
-that works.
-
-.. code-block:: console
-
- sudo vi /etc/apache2/mods-available/dav_svn.conf
-
-Uncomment and change to :code:`<Location /svn/p/test>`. Set
-:code:`SVNParentPath /srv/svn/p/test` Then run:
-
-.. code-block:: console
-
- sudo service apache2 reload
-
-Test at http://localhost/svn/p/test/code/ (`localhost:8088` if using Vagrant)
-
-That configuration works only for the repositories in a single project. You must either
-create a new configuration for each project within Allura, or compile a patch
-to make `SVNParentPath` be recursive. The patch is at http://pastie.org/8550810
-and must be applied to the source of Subversion 1.7's mod_dav_svn and then
-recompiled and installed. (See http://subversion.tigris.org/issues/show_bug.cgi?id=3588
-for the request to include this patch in Subversion itself). Once that is working,
-you can modify :file:`dav_svn.conf` to look like:
-
-.. code-block:: apache
-
- <Location /svn>
- DAV svn
- SVNParentPath /srv/svn
- ...
-
-Then Apache SVN will serve repositories for all Allura projects and subprojects.
-
-.. warning::
-
- This configuration has no authentication and is suitable for development only. See :ref:`the next section <auth_apache>` for auth config.
-
-
-.. _auth_apache:
-
-Configuring Auth with Apache
-----------------------------
-
-This is the easiest way to integrate authentication and authorization for SCM access with Allura. It uses
-mod_python and the handler in :file:`scripts/ApacheAccessHandler.py` to query Allura directly
-for auth and permissions before allowing access to the SCM. Of course, this only works
-for SCM access over HTTP(S).
-
-First, you need to ensure that mod_python is installed:
-
-.. code-block:: console
-
- sudo aptitude install libapache2-mod-python
-
-Then, in the VirtualHost section where you proxy SCM requests to git, SVN, or Hg, add the
-access handler, e.g.:
-
-.. code-block:: console
-
- sudo vi /etc/apache2/sites-available/default
-
-.. code-block:: apache
-
- <LocationMatch "^/(git|svn|hg)/">
- AddHandler mod_python .py
- # Change this path if needed:
- PythonAccessHandler /home/vagrant/src/allura/scripts/ApacheAccessHandler.py
- AuthType Basic
- AuthName "SCM Access"
- AuthBasicAuthoritative off
- # Change this path if needed:
- PythonOption ALLURA_VIRTUALENV /home/vagrant/env-allura
- # This routes back to the allura webapp, port 8080 if running with paster server (~/start_allura)
- # In a production environment, run allura with a real WSGI server, and
- # change the IP address and port number as appropriate.
- # And use https if possible, since the username and password are otherwise
- # sent in the clear to Allura.
- PythonOption ALLURA_AUTH_URL http://127.0.0.1:8080/auth/do_login
- PythonOption ALLURA_PERM_URL http://127.0.0.1:8080/auth/repo_permissions
- </LocationMatch>
-
-.. code-block:: console
-
- sudo service apache2 reload
-
-To test that it's working, run: :command:`git ls-remote
-http://localhost/git/p/test/git/` (if using Vagrant, use :code:`localhost:8088`
-from your host machine). If there is no output, that is fine (it's an empty
-repo). If it errors, look in :file:`/var/log/apache2/error.log` for the error
-message.
-
-.. warning::
-
- Currently, for Mercurial, the handler doesn't correctly distinguish read
- and write requests and thus requires WRITE permission for every request.
- See ticket #7288
-
-
-Advanced Alternative
---------------------
-
-An advanced alternative for SCM hosting using :ref:`SSH, LDAP, and a FUSE driver <scm_hosting_ssh>` is available.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/scm_host_ssh.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/scm_host_ssh.rst b/Allura/docs/scm_host_ssh.rst
deleted file mode 100644
index 81b21d8..0000000
--- a/Allura/docs/scm_host_ssh.rst
+++ /dev/null
@@ -1,197 +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.
-
-.. _scm_hosting_ssh:
-
-Configuring Git/SVN/Hg to use Allura auth via LDAP and ssh
-==========================================================
-
-The following instructions will use a chroot, a custom FUSE driver, and LDAP.
-Once completed, an ssh-based configuration of Git, SVN, or Hg that has repos in
-the chroot directory will authenticate the users against LDAP and authorize via an Allura API.
-Allura will be configured to authenticate against LDAP as well.
-
-.. note::
-
- The previous git & svn configuration instructions are not ssh-based, so will not work with this configuration.
- You'll have to reconfigure git & svn to use ssh:// instead of http or svn protocols.
-
-We assume you are using a version of Ubuntu with
-support for schroot and debootstrap. We will use a chroot jail to allow users to
-access their repositories via ssh.
-
-Install a chroot environment
-----------------------------
-
-These instructions are based on the documentation in `Debootstrap Chroot`_. and `OpenLDAPServer`_.
-
-Install debootstrap and schroot: :program:`aptitude install debootstrap schroot`
-
-Append the following text to the file :file:`/etc/schroot/schroot.conf`
-
-.. code-block:: ini
-
- [scm]
- description=Ubuntu Chroot for SCM Hosting
- type=directory
- directory=/var/chroots/scm
- script-config=scm/config
-
-Create a directory :file:`/etc/schroot/scm` and populate it with some files:
-
-.. code-block:: console
-
- # mkdir /etc/schroot/scm
- # cat > /etc/schroot/scm/config <<EOF
- FSTAB="/etc/schroot/scm/fstab"
- COPYFILES="/etc/schroot/scm/copyfiles"
- NSSDATABASES="/etc/schroot/scm/nssdatabases"
- EOF
- # cat > /etc/schroot/scm/fstab <<EOF
- /proc /proc none rw,rbind 0 0
- /sys /sys none rw,rbind 0 0
- /dev /dev none rw,rbind 0 0
- /tmp /tmp none rw,bind 0 0
- EOF
- # cat > /etc/schroot/scm/copyfiles <<EOF
- /etc/resolv.conf
- EOF
- # cat > /etc/schroot/scm/nssdatabases <<EOF
- services
- protocols
- networks
- hosts
- EOF
-
-Create a directory :file:`/var/chroots/scm` and create the bootstrap environment. (You may substitute a mirror from the `ubuntu mirror list`_ for archive.ubuntu.com)
-
-.. code-block:: console
-
- $ sudo mkdir -p /var/chroots/scm
- $ sudo debootstrap --variant=buildd --arch amd64 --components=main,universe --include=git,mercurial,subversion,openssh-server,slapd,ldap-utils,ldap-auth-client,curl maverick /var/chroots/scm http://archive.ubuntu.com/ubuntu/
-
-Test that the chroot is installed by entering it:
-
-.. code-block:: console
-
- # schroot -c scm -u root
- (scm) # logout
-
-Configure OpenLDAP in the Chroot
---------------------------------
-
-Copy the ldap-setup script into the chroot environment:
-
-.. code-block:: console
-
- $ sudo cp Allura/ldap-setup.py Allura/ldap-userconfig.py /var/chroots/scm
- $ sudo chmod +x /var/chroots/scm/ldap-*.py
-
-Log in to the chroot environment:
-
-.. code-block:: console
-
- # schroot -c scm -u root
-
-Run the setup script, following the prompts:
-
-.. code-block:: console
-
- (scm) # python /ldap-setup.py
-
-In particular, you will need to answer the following questions (substitute your custom suffix if you are not using dc=localdomain):
-
-* Should debconf manage LDAP configuration? **yes**
-* LDAP server Uniform Resource Identifier: **ldapi:///**
-* Distinguished name of the search base: **dc=localdomain**
-* LDAP version to use: **1** (version 3)
-* Make local root Database admin: **yes**
-* Does the LDAP database require login? **no**
-* LDAP account for root: **cn=admin,dc=localdomain**
-* LDAP root account password: *empty*
-* Local crypt to use when changing passwords: **2** (crypt)
-* PAM profiles to enable: **2**
-
-Update the chroot ssh configuration
------------------------------------
-
-Update the file :file:`/var/chroot/scm/etc/ssh/sshd_config`, changing the port directive:
-
-.. code-block:: guess
-
- # Port 22
- Port 8022
-
-Setup the Custom FUSE Driver
-----------------------------
-
-Copy the accessfs script into the chroot environment:
-
-.. code-block:: console
-
- $ sudo cp fuse/accessfs.py /var/chroots/scm
-
-Configure allura to point to the chrooted scm environment:
-
-.. code-block:: console
-
- $ sudo ln -s /var/chroots/scm /srv/git
- $ sudo ln -s /var/chroots/scm /srv/hg
- $ sudo ln -s /var/chroots/scm /srv/svn
-
-Log in to the chroot environment & install packages:
-
-.. code-block:: console
-
- # schroot -c scm -u root
- (scm) # apt-get install python-fuse
-
-Create the SCM directories:
-
-.. code-block:: console
-
- (scm) # mkdir /scm /scm-repo
-
-Mount the FUSE filesystem:
-
-.. code-block:: console
-
- (scm) # python /accessfs.py /scm-repo -o allow_other -s -o root=/scm
-
-Start the SSH daemon:
-
-.. code-block:: console
-
- (scm) # /etc/init.d/ssh start
-
-Configure Allura to Use the LDAP Server
----------------------------------------
-
-Set the following values in your .ini file:
-
-.. code-block:: ini
-
- auth.method = ldap
-
- auth.ldap.server = ldap://localhost
- auth.ldap.suffix = ou=people,dc=localdomain
- auth.ldap.admin_dn = cn=admin,dc=localdomain
- auth.ldap.admin_password = secret
-
-.. _Debootstrap Chroot: https://help.ubuntu.com/community/DebootstrapChroot
-.. _OpenLDAPServer: https://help.ubuntu.com/10.10/serverguide/C/openldap-server.html
-.. _ubuntu mirror list: https://launchpad.net/ubuntu/+archivemirrors
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/tutorials/testing.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/tutorials/testing.rst b/Allura/docs/tutorials/testing.rst
deleted file mode 100644
index 646a24e..0000000
--- a/Allura/docs/tutorials/testing.rst
+++ /dev/null
@@ -1,76 +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.
-
-Writing Tests for Allura Tools
-==============================
-
-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 you will often
-need to setup pylons global objects before your test. If the code under test
-uses pylons globals (like `g` and `c`), but your test doesn't require the
-fully-loaded wsgi app, you can do something like this:
-
-.. code-block:: python
-
- from pylons import tmpl_context as c
-
- from alluratest.controller import setup_unit_test
- from allura.lib import helpers a h
- from allura import model as M
-
- def setUp():
- # set up pylons globals
- setup_unit_test()
-
- # set c.project and c.app
- h.set_context('test', 'wiki', neighborhood='Projects'):
- 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.
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/using.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/using.rst b/Allura/docs/using.rst
deleted file mode 100644
index d9be6fe..0000000
--- a/Allura/docs/using.rst
+++ /dev/null
@@ -1,58 +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.
-
-We don't have much end-user help for Allura yet. SourceForge projects use Allura,
-though, so their support documentation may be useful to anyone using Allura:
-
-Configuring your project
-------------------------
-
-See SourceForge help page: https://sourceforge.net/p/forge/documentation/Create%20a%20New%20Project/
-
-Note there are some SourceForge-specific references that don't apply to other Allura instances.
-
-
-Using tickets
--------------
-
-See SourceForge help page: https://sourceforge.net/p/forge/documentation/Tickets/
-
-
-Using the wiki
---------------
-
-See SourceForge help page: https://sourceforge.net/p/forge/documentation/Wiki/
-
-
-Using a discussion forum
-------------------------
-
-See SourceForge help page: https://sourceforge.net/p/forge/documentation/Discussion/
-
-
-Adding an external link
------------------------
-
-See SourceForge help page: https://sourceforge.net/p/forge/documentation/External%20Link/
-
-
-Using markdown syntax
----------------------
-
-Everything in Allura uses Markdown formatting, with several customizations and macros
-specifically for Allura. There are "Formatting Help" buttons throughout Allura for
-easy reference to the Markdown syntax. One such page is https://forge-allura.apache.org/p/allura/wiki/markdown_syntax/
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/INSTALL.markdown
----------------------------------------------------------------------
diff --git a/INSTALL.markdown b/INSTALL.markdown
index f552a2a..220d11f 100644
--- a/INSTALL.markdown
+++ b/INSTALL.markdown
@@ -126,7 +126,7 @@ The default configuration stores repos in `/srv`, so we need to create those dir
If you don't have `sudo` permission or just want to store them somewhere else, change the `/srv` paths in `development.ini`
-If you want to set up remote access to the repositories, see <http://forge-allura.apache.org/docs/scm_host.html>
+If you want to set up remote access to the repositories, see <http://forge-allura.apache.org/docs/getting_started/scm_host.html>
### Allura task processing
@@ -159,7 +159,7 @@ register a new project in your own forge, visit /p/add_project
## Extra
* Read more documentation: <http://forge-allura.apache.org/docs/>
- * Including how to enable extra features: <http://forge-allura.apache.org/docs/installation.html>
+ * Including how to enable extra features: <http://forge-allura.apache.org/docs/getting_started/installation.html>
* Ask questions and discuss Allura on the <http://mail-archives.apache.org/mod_mbox/allura-dev/>
* Run the test suite (slow): `$ ALLURA_VALIDATION=none ./run_tests`
* File bug reports at <https://forge-allura.apache.org/p/allura/tickets/new/> (login required)
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/requirements.txt
----------------------------------------------------------------------
diff --git a/requirements.txt b/requirements.txt
index 5e67556..6de0f60 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -79,3 +79,4 @@ WebTest==1.4.0
testfixtures==3.0.0
q==2.3
WebError==0.10.3
+sphinx-rtd-theme==0.1.6