more work in the documentation. added docs/tinderbox.rst

4 files changed, 143 insertions, 10 deletions

diff --git a/docs/development.rst b/docs/development.rst
index 4c52cbd..ed171b5 100644
--- a/docs/development.rst
+++ b/docs/development.rst
@@ -9,8 +9,8 @@ Development
 Running the test suites
 -----------------------
 
-You can run the tests suites using the script *run_tests.py* that can be
-found in the directory *scripts* in the `source tarballs`_ (since 0.1) or
+You can run the tests suites using the script ``run_tests.py`` that can be
+found in the directory ``scripts`` in the `source tarballs`_ (since 0.1) or
 in the `Mercurial repository`_
 
 .. _`source tarballs`: http://files.rafaelmartins.eng.br/distfiles/g-octave/
diff --git a/docs/index.rst b/docs/index.rst
index da0fd47..e049e00 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -33,5 +33,5 @@ Contents
    :maxdepth: 2
 
    userguide
-   tinderbox
    development
+   tinderbox
diff --git a/docs/tinderbox.rst b/docs/tinderbox.rst
new file mode 100644
index 0000000..4e55076
--- /dev/null
+++ b/docs/tinderbox.rst
@@ -0,0 +1,133 @@
+Tinderbox
+=========
+
+g-Octave provides a script to run build tests for all the octave-forge
+packages. This script is not intended to be used by end-users, only
+developers.
+
+
+Creating the environment
+------------------------
+
+We recommend the use of the script inside a chroot environment. For this
+you'll need to download the latest stage3 tarball from the Gentoo mirrors
+and create a basic environment::
+    
+    # cd /home/user/g-octave
+    # tar xvjpf stage3-*.tar.bz2
+
+
+Configuring the environment
+---------------------------
+
+You should copy the needed files from your Gentoo installation to the
+chroot environment, to ease the configuration. ::
+
+    # cp /etc/resolv.conf /home/user/g-octave/etc
+    # cp /etc/make.conf /home/user/g-octave/etc
+
+You may also need some files from ``/etc/portage``
+
+
+Mounting filesystems/directories
+--------------------------------
+
+You should mount your current ``/usr/portage`` inside the chroot. ::
+
+    # mkdir /home/user/g-octave/usr/portage
+    # mount -o bind /usr/portage /home/user/g-octave/usr/portage
+
+Mounting ``/proc`` and ``/dev``::
+
+    # mount -t proc none /home/user/g-octave/proc
+    # mount -o bind /dev /home/user/g-octave/dev
+
+
+Entering the chroot environment
+-------------------------------
+
+::
+
+    # chroot /home/user/g-octave /bin/bash
+    # env-update
+    # source /etc/profile
+    # export PS1="(g-octave) $PS1"
+
+
+Updating the packages and installing the dependencies
+-----------------------------------------------------
+
+::
+
+    # emerge -avuDN system
+    # emerge av mercurial pycurl
+
+
+Cloning the g-octave repository
+-------------------------------
+
+::
+    
+    # cd
+    # hg clone http://hg.rafaelmartins.eng.br/g-octave/
+
+
+Configuring g-Octave
+--------------------
+
+::
+
+    # cd g-octave
+    # cp etc/g-octave.cfg /etc
+
+You should edit the file ``/etc/g-octave.cfg`` and append the lines below
+(with your data)::
+
+    trac_user = username
+    trac_passwd = password
+
+For this you'll need to register_ at the `g-Octave project page`_, in order
+to be able to create new tickets and attachments.
+
+.. _register: http://g-octave.rafaelmartins.eng.br/register
+.. _`g-Octave project page`: http://g-octave.rafaelmartins.eng.br/
+
+Now you need to add the g-octave overlay to the Portage configuration file
+``/etc/make.conf`` (use the same overlay path from ``/etc/g-octave.cfg``)::
+
+    # echo 'PORTDIR_OVERLAY="/usr/local/portage/g-octave ${PORTDIR_OVERLAY}" >> /etc/make.conf
+
+
+Running the script
+------------------
+
+Update the package database::
+
+    # ./scripts/g-octave --sync
+
+Run the test suites::
+
+    # ./scripts/run_tests.py
+
+Make sure that you have activated all the ``USE`` flags needed by octave::
+
+    # emerge -vp octave
+
+Run the script::
+    
+    # ./scripts/tinderbox.py
+
+At the end, the script should uninstall all the octave-forge packages
+directly installed. If you want to remove the dependencies, run::
+
+    # emerge -av --depclean
+
+
+Umounting filesystems/directories
+---------------------------------
+
+::
+    
+    # exit
+    # cd
+    # umount /home/user/g-octave/{proc,dev,usr/portage}
diff --git a/docs/userguide.rst b/docs/userguide.rst
index 778ee96..7699eb5 100644
--- a/docs/userguide.rst
+++ b/docs/userguide.rst
@@ -17,10 +17,10 @@ After you have the overlay installed, you can install the package, using: ::
     
     # emerge -av app-portage/g-octave
 
-We have 2 ebuilds, one for the latest stable release (for ~x86 and ~amd64)
+We have 2 ebuilds, one for the latest stable release (for ``~x86`` and ``~amd64``)
 and one live ebuild, that installs g-Octave from the mercurial repository
 (without keywords). If you want to use the live ebuild, you need to unmask
-this ebuild, adding this to /etc/portage/package.keywords: ::
+this ebuild, adding this to ``/etc/portage/package.keywords``::
 
     app-portage/g-octave **
 
@@ -29,7 +29,7 @@ features, or for developers.
 
 Stable users (with x86 or amd64) that wants to test the latest release
 will need to unmask the ebuild too, adding this to
-/etc/portage/package.keywords (e.g. for x86): ::
+/etc/portage/package.keywords (e.g. for ``x86``)::
 
     app-portage/g-octave ~x86
 
@@ -38,7 +38,7 @@ The source code of g-Octave can be found in this Mercurial repository:
 http://hg.rafaelmartins.eng.br/g-octave/
 
 You can clone the mercurial repository using this command (with Mercurial
-installed, of course): ::
+installed, of course)::
     
     $ hg clone http://hg.rafaelmartins.eng.br/g-octave/
 
@@ -51,9 +51,9 @@ Configuring g-Octave
 --------------------
 
 If you installed g-Octave correctly, you should find a configuration file
-at */etc/g-octave.cfg*.
+at ``/etc/g-octave.cfg``.
 
-The main options are *db* and *overlay*, that defines the directory paths
+The main options are ``db`` and ``overlay``, that defines the directory paths
 for the package database and the generated overlay, respectively.
 
 Other options are available. Please read the comments in the configuration
@@ -76,7 +76,7 @@ Configuring your package manager
 Portage needs to be able to find the ebuilds generated by g-Octave, then
 you'll need to add the directory path of the overlay (configured in the
 previous step) to the variable ``PORTDIR_OVERLAY``, in the file
-*/etc/make.conf*.
+``/etc/make.conf``.
 
 You can use something like this command: ::