updated documentation

docs/conf.py

@@ -45,9 +45,9 @@
 # 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 @@
 
 # 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

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`_.

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

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,77 +67,48 @@ 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
 ------------------
 
 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
 

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``.