updated documentation

6 files changed, 207 insertions, 106 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 9a7353c..0d4cd09 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -45,9 +45,9 @@ copyright = u'2010, Rafael Goncalves Martins'
 # built documents.
 #
 # The short X.Y version.
-version = '0.3'
+version = '0.4'
 # The full version, including alpha/beta/rc tags.
-release = '0.3'
+release = '0.4'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -93,7 +93,7 @@ highlight_language = 'text'
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+html_theme = 'nature'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
diff --git a/docs/development.rst b/docs/development.rst
index 8e3feb5..cd0610e 100644
--- a/docs/development.rst
+++ b/docs/development.rst
@@ -2,7 +2,13 @@ Development
 ===========
 
 :Source code: http://git.overlays.gentoo.org/gitweb/?p=proj/g-octave.git
-:Bugs to: rafael [at] rafaelmartins [dot] eng [dot] br
+:Bugs to: http://www.g-octave.org/trac/newticket
+
+.. warning::
+    
+    This section of the documentation is supposed to be used by g-Octave
+    developers. End-users should not need to read this!
+
 
 Running the test suites
 -----------------------
@@ -11,44 +17,105 @@ You can run the tests suites using the script ``run_tests.py`` that can be
 found in the directory ``scripts`` in the recent `source tarballs`_ or
 in the `Git repository`_
 
-.. _`source tarballs`: http://soc.dev.gentoo.org/~rafaelmartins/g-octave/
+.. _`source tarballs`: http://www.g-octave.org/releases/
 .. _`Git repository`: http://git.overlays.gentoo.org/gitweb/?p=proj/g-octave.git
 
 ::
     
     $ scripts/run_tests.py
 
-If some test is broken, report me a bug by email. The bug tracker is
-temporary disabled.
 
+If some test is broken, please use the `bug tracker`_.
+
+.. _`bug tracker`: http://www.g-octave.org/trac/newticket
+
+
+Working on the package database
+-------------------------------
+
+Package databases are Git repositories with the DESCRIPTION files, patches
+and a ``info.json`` file with the non-octave dependencies and the licenses
+of the packages.
+
+We're using github to host the package database:
 
-Creating source tarballs from the octave-forge SVN repository
--------------------------------------------------------------
+http://github.com/rafaelmartins/g-octave-db/
+
+If you want to fix something on the package database, please fork the
+repository, change it and fill a merge request.
+
+
+Updating the package database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We have a script to update the package database: ``contrib/manage_pkgdb.py``.
+You just need to clone the git repository and create a directory to store
+the source tarballs, that are used to extract the DESCRIPTION files and
+build the package database.
+
+g-Octave will install the script on ``/usr/share/g-octave/contrib``
+
+::
 
-We have a script to create source tarballs for all the packages,
-using the latest stable revision from the octave-forge SVN repo.
+    $ git clone git+ssh://git@github.com:your_username/g-octave-db.git
+    $ mkdir tarballs
+    $ /usr/share/g-octave/contrib/manage_pkgdb.py tarballs g-octave-db
 
-To use it, add a ``pkg_cache`` option to your configuration file with
-the directory where you want to save the generated tarballs and, after
-clone the Mercurial repository or download the source tarball, run from
-the root of the source tree::
+The first parameter of the script is the path to the directory that will
+store the tarballs. The second parameter is the path to the local clone
+of your forked git repository.
 
-    $ scripts/package_sources.py
 
+Updating the list of external dependencies and licenses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Creating a package database from the previously created source tarballs
------------------------------------------------------------------------
+We have a script to update the JSON file that contains the external
+dependencies (non-octave packages from the portage tree) and the licenses
+(the license names used by the octave-forge developers doesn't matches
+with the names used on the Portage tree).
 
-You should want to also create a package database. For this, keep the
-``pkg_cache`` option in your configuration file pointing to the directory
-with your source tarballs and run from the root of the source tree::
+This script will be also installed on ``/usr/share/g-octave/contrib``
+
+::
+    
+    $ /usr/share/g-octave/contrib/manage_info.py g-octave-db/info.json
+
+The script is interactive and the argument is the path to the ``info.json``
+file, that lives on the root of the Git repository of the package database.
+
+The script will suggest some matches for each dependency. For the licenses
+you need to find the best match at the directory ``${PORTDIR}/licenses``,
+where ${PORTDIR} is the path to your Portage tree (``/usr/portage``
+usually).
+
+
+Commiting the changes
+~~~~~~~~~~~~~~~~~~~~~
+
+You can use the script ``manage_pkgdb.py`` to commit the changes::
+
+    $ /usr/share/g-octave/contrib/manage_pkgdb.py --commit tarballs g-octave-db
+
+The script will do a last check on your updates and commit the stuff to
+your fork repository.
+
+
+Using your fork as package database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to use your fork as package database, change the variable
+``db_mirror`` on the file ``/etc/g-octave.cfg`` to something like::
+    
+    db_mirror = github://your_username/g-octave-db
 
-    $ scripts/package_database.py /path/to/your/new/database.tar.gz
 
+Sending patches to the source code
+----------------------------------
 
-Sending patches
----------------
+The source code of g-Octave lives on a repository on the Gentoo Linux
+infrastructure. ::
 
-You can send git formated patches to me via email.
+    $ git clone git://git.overlays.gentoo.org/proj/g-octave.git
 
-More information will be available soon.
+You can change what you need, commit, generate a Git-formated patch and
+attach it to a new ticket on our `bug tracker`_.
diff --git a/docs/index.rst b/docs/index.rst
index 2a1df26..95ccc93 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,8 +7,10 @@ Welcome to g-Octave's documentation!
 ====================================
 
 :Author: Rafael Goncalves Martins
-:Source code: http://git.overlays.gentoo.org/gitweb/?p=proj/g-octave.git
-:Bugs to: rafael [at] rafaelmartins [dot] eng [dot] br
+:Website: http://www.g-octave.org/
+:Source code: http://www.g-octave.org/trac/browser
+              http://git.overlays.gentoo.org/gitweb/?p=proj/g-octave.git
+:Bugs to: http://www.g-octave.org/trac/newticket
 :Version: |release|
 
 .. topic:: Overview
@@ -36,5 +38,6 @@ Contents
     
    quickstart
    userguide
+   upgrading
    development
    tinderbox
diff --git a/docs/tinderbox.rst b/docs/tinderbox.rst
index 5141bf6..6f51502 100644
--- a/docs/tinderbox.rst
+++ b/docs/tinderbox.rst
@@ -2,13 +2,13 @@ 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.
+packages automatically and report issues to the `bug tracker`_.
 
-.. topic:: Warning!
+.. _`bug tracker`: http://www.g-octave.org/trac/report/9
 
-    The automated bug reports are broken right now, because the Trac instance
-    is currently offline and being moved to the Gentoo Linux infrastructure.
+.. warning::
+
+    This script is not intended to be used by end-users, only developers.
 
 
 Creating the environment
@@ -37,7 +37,9 @@ You may also need some files from ``/etc/portage``
 Mounting filesystems/directories
 --------------------------------
 
-You should mount your current ``/usr/portage`` inside the chroot dir::
+You should mount your current ``${PORTDIR}`` (e.g. ``/usr/portage``)
+inside the chroot dir (the script will force the use of Portage to build
+the packages)::
 
     # mkdir /home/user/g-octave/usr/portage
     # mount -o bind /usr/portage /home/user/g-octave/usr/portage
@@ -65,54 +67,24 @@ Updating the packages and installing the dependencies
 ::
 
     # emerge -avuDN system
-    # emerge -av mercurial pycurl
-
-
-Getting the source code
------------------------
-
-Using the Git repository::
-    
-    # cd
-    # git clone git://git.overlays.gentoo.org/proj/g-octave.git
-    # cd g-octave
-
-
-Using the source tarball::
-    
-    # cd
-    # wget http://files.rafaelmartins.eng.br/distfiles/g-octave/g-octave-<VERSION>.tar.gz
-    # tar xvzf g-octave-<VERSION>.tar.gz
-    # cd g-octave-<VERSION>
+    # USE="git" emerge -av layman
+    # layman -a science
+    # FEATURES="test" USE="sync" emerge -av g-octave
 
 
 Configuring g-Octave
 --------------------
 
-::
-
-    # cp etc/g-octave.cfg /etc
-
-.. topic:: Warning!
-
-    This is currently broken!
-
-You should edit the file ``/etc/g-octave.cfg`` and append the lines below
-(with your data)::
+You should `create an account`_ on the `g-Octave project page`_, 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.
+.. _`create an account`: http://www.g-octave.org/trac/register
+.. _`g-Octave project page`: http://www.g-octave.org/trac/
 
-.. _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
+Now you're done with the configuration.
 
 
 Running the script
@@ -120,22 +92,23 @@ Running the script
 
 Update the package database::
 
-    # ./scripts/g-octave --sync
+    # g-octave --sync
 
-Run the test suites::
+Make sure that you have activated all the ``USE`` flags needed on octave::
 
-    # ./scripts/run_tests.py
+    # emerge -vp octave
 
-Make sure that you have activated all the ``USE`` flags needed by octave::
+And build it first::
 
-    # emerge -vp octave
+    # emerge octave
 
-Run the script::
+Now that you already have the main dependency of the packages installed
+and g-Octave configured, you can run the script::
     
-    # ./scripts/tinderbox.py
+    # /usr/share/g-octave/contrib/manage_pkgdb.py
 
-At the end, the script should uninstall all the octave-forge packages
-directly installed. If you want to remove the dependencies, run::
+The packages are installed with the ``--oneshot`` option. To remove them
+with the dependencies, run::
 
     # emerge -av --depclean
 
diff --git a/docs/upgrading.rst b/docs/upgrading.rst
new file mode 100644
index 0000000..a21b1e9
--- /dev/null
+++ b/docs/upgrading.rst
@@ -0,0 +1,24 @@
+Upgrading g-Octave
+==================
+
+Quick notes for users upgrading from older versions of g-Octave.
+
+
+From ``0.3`` to ``0.4``
+-----------------------
+
+This version broke the compatibility with old package databases and some
+external files.
+
+You'll need to remove the directories of the package database and the
+overlay (``db`` and ``overlay`` options from the configuration file).
+
+To know what are the current values, type::
+    
+    $ g-octave --config db
+    $ g-octave --config overlay
+
+And remove both directories!
+
+If you installed g-Octave with ``USE="-sync"``, please remove those
+directories before run ``emerge --config g-octave``.
diff --git a/docs/userguide.rst b/docs/userguide.rst
index 252818b..d4ee524 100644
--- a/docs/userguide.rst
+++ b/docs/userguide.rst
@@ -1,8 +1,7 @@
 User Guide
 ==========
 
-This is a small user guide for g-Octave, with some instructions to the
-end user.
+This is an user guide with some instructions to the end-user.
 
 
 Installing g-Octave
@@ -14,15 +13,15 @@ To install it with ``layman`` and ``git`` installed, type::
 
     # layman -a science
 
-
 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``)
-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 the line below to ``/etc/portage/package.keywords``::
+We have 2 ebuilds, one for with latest stable release (for ``~x86`` and
+``~amd64``) and one live ebuild, that installs g-Octave from the Git
+repository (without keywords). If you want to use the live ebuild, you
+need to unmask them adding the line below to your
+``/etc/portage/package.keywords``::
 
     app-portage/g-octave **
 
@@ -46,7 +45,18 @@ installed, of course)::
 
 The release tarballs can be found here:
 
-http://soc.dev.gentoo.org/~rafaelmartins/g-octave/releases/
+http://www.g-octave.org/releases/
+
+
+USE flags
+~~~~~~~~~
+
+g-Octave have 2 USE flags:
+
+- ``doc``: Install this documentation. Depends on ``dev-python/sphinx``.
+- ``sync``: Enable the ``--sync`` command-line option. Available only
+  on the ebuilds of stable releases. The live ebuild will enable this
+  feature by default.
 
 
 Configuring g-Octave
@@ -71,8 +81,8 @@ Using environment variables
 
 All the options from the configuration file can be overrided with environment
 variables. The environment variable name starts with ``GOCTAVE_`` and
-ends with the option name in uppercase. e.g. ``GOCTAVE_OVERLAY`` will
-override the option ``overlay`` from the config file.
+ends with the option name in uppercase. for example, ``GOCTAVE_OVERLAY``
+will override the option ``overlay`` from the config file.
 
 Usage example::
     
@@ -97,8 +107,9 @@ Syncronizing the package database
 ---------------------------------
 
 Currently g-Octave depends on an external package database, in order to
-create the ebuilds for the packages. You'll need to fetch this database
-in the first time that you run g-Octave: ::
+create the ebuilds for the packages (only if you installed g-Octave with
+``USE="-sync"``). You'll need to fetch this database in the first time
+that you run g-Octave (and whenever you want to updates): ::
     
     # g-octave --sync
 
@@ -112,21 +123,21 @@ g-octave can use all the 3 package managers available on Gentoo Linux:
 You just need to setup the option ``package_manager`` with the lowercase
 name of the package manager: ``portage``, ``paludis``, ``pkgcore``.
 
-If you're using Paludis or Pkgcore, you'll need to configure the overlay
+If you're using **Paludis** or **Pkgcore**, you'll need to configure the overlay
 in your package manager configuration files. Please check the documentation
 of your package manager:
 
 - Paludis: http://paludis.pioto.org/
 - Pkgcore: http://www.pkgcore.org/
 
-Portage works out of the box.
+**Portage** works out of the box.
 
 
 Installing packages
 -------------------
 
-From the stable source tarballs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+From the upstream source tarballs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can list all the available packages using this command: ::
     
@@ -155,6 +166,9 @@ of packages:
     Ask before install the package
 ``-p`` or ``--pretend``
     Only pretend the installation of the package
+``-1`` or ``--oneshot``
+    Do not add the packages to the world file for later updating.
+
 
 You can get some information about the package using this command: ::
 
@@ -168,20 +182,22 @@ or ::
 From the octave-forge SVN repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you want to test some new feature, or to use the new version of the
-packages ever, you'll like to install your packages directly from the
+If you want to test some new feature or to always use the newest version
+of the packages, you'll like to install the packages directly from the
 SVN repository.
 
-To install a package from SVN, type::
+To install a package from SVN, you'll need to configure g-Octave, changing
+the value of the variable ``use_scm`` on the file ``/etc/g-octave.cfg``
+to ``true``. After that, type::
     
-    # g-octave packagename-9999
+    # g-octave packagename
 
-All the common g-octave options for install packages are allowed, and
-the special version ``9999`` says to g-octave that you want to use the
-SVN version.
+If you only want to install a single package, you can use the command-line
+option ``--scm``.
 
-In order to be able to install packages from svn you need to install
-g-octave with the USE flag ``svn`` enabled.
+If you enabled the installation from SVN on the configuration file and
+wants to install a stable version, you can use the command-line option
+``--no-scm``.
 
 
 Updating packages
@@ -231,3 +247,21 @@ or ::
     # g-octave -C packagename-version
 
 The options ``--ask`` and ``--verbose`` are also supported.
+
+
+Troubleshooting
+---------------
+
+Some times the generated ebuilds can be broken for some reason. To fix
+this you can use the command-line option ``--force``, that will rebuild
+the ebuild or the command-line option ``--force-all``, that rebuild the
+entire overlay.
+
+If you got some problem with corrupted sources, please remove the tarball
+from the ``${DISTDIR}`` and run::
+
+    # g-octave --force packagename
+
+If you still have problems, please fill a ticket on our `bug tracker`_
+
+.. _`bug tracker`: http://www.g-octave.org/trac/newticket