From 596d154030123ca25dc160b17a8777e927466f3b Mon Sep 17 00:00:00 2001 From: "Rafael G. Martins" Date: Wed, 4 Aug 2010 00:20:56 -0300 Subject: [PATCH] updated documentation --- docs/conf.py | 6 +-- docs/development.rst | 113 ++++++++++++++++++++++++++++++++++--------- docs/index.rst | 7 ++- docs/tinderbox.rst | 79 ++++++++++-------------------- docs/upgrading.rst | 24 +++++++++ docs/userguide.rst | 84 ++++++++++++++++++++++---------- 6 files changed, 207 insertions(+), 106 deletions(-) create mode 100644 docs/upgrading.rst 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 @@ # 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 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-.tar.gz - # tar xvzf g-octave-.tar.gz - # cd g-octave- + # 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