added some sphinx documentation

4 files changed, 198 insertions, 9 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 2bc2727..c78a9b9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -31,7 +31,7 @@ templates_path = ['_templates']
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8'
+source_encoding = 'utf-8'
 
 # The master toctree document.
 master_doc = 'index'
@@ -83,6 +83,8 @@ exclude_trees = ['_build']
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+highlight_language = 'text'
+
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
diff --git a/docs/development.rst b/docs/development.rst
new file mode 100644
index 0000000..4c52cbd
--- /dev/null
+++ b/docs/development.rst
@@ -0,0 +1,33 @@
+Development
+===========
+
+:Source code: http://hg.rafaelmartins.eng.br/g-octave/
+:Bug tracker: http://g-octave.rafaelmartins.eng.br/
+
+.. _`bug tracker`: http://g-octave.rafaelmartins.eng.br/
+
+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
+in the `Mercurial repository`_
+
+.. _`source tarballs`: http://files.rafaelmartins.eng.br/distfiles/g-octave/
+.. _`Mercurial repository`: http://hg.rafaelmartins.eng.br/g-octave/
+
+::
+    
+    $ scripts/run_tests.py
+
+If some test is broken, please create a ticket in the `bug tracker`_.
+A quick registration is needed.
+
+
+Sending patches
+---------------
+
+You can send mercurial/git formated patches, attaching the patch to a new
+bug in the `bug tracker`_.
+
+More information will be available soon.
diff --git a/docs/index.rst b/docs/index.rst
index 5c3041b..da0fd47 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,15 +6,32 @@
 Welcome to g-Octave's documentation!
 ====================================
 
-Contents:
+:Author: Rafael Goncalves Martins
+:Source code: http://hg.rafaelmartins.eng.br/g-octave/
+:Bug tracker: http://g-octave.rafaelmartins.eng.br/
+:Version: |release|
 
-.. toctree::
-   :maxdepth: 2
+.. topic:: Overview
+
+    g-Octave is a tool that generates and installs ebuilds for
+    `Octave-Forge`_ packages "on-the-fly" to `Gentoo Linux`_, using
+    Portage_. It's capable to generate ebuilds and Manifest files for
+    the packages, and to install them using an autogenerated overlay
+    (named g-octave). g-Octave can also handle patches to the packages
+    automatically. The command line interface tries to be very similar
+    to the interface of the *emerge* tool. 
+
+.. _`Octave-Forge`: http://octave.sourceforge.net/
+.. _`Gentoo Linux`: http://www.gentoo.org/
+.. _Portage: http://www.gentoo.org/proj/en/portage/
 
-Indices and tables
-==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
 
+   userguide
+   tinderbox
+   development
diff --git a/docs/userguide.rst b/docs/userguide.rst
new file mode 100644
index 0000000..778ee96
--- /dev/null
+++ b/docs/userguide.rst
@@ -0,0 +1,137 @@
+User Guide
+==========
+
+This is a small user guide for g-Octave, with some instructions to the
+end user.
+
+
+Installing g-Octave
+-------------------
+
+The ebuilds for g-Octave will be available on the Portage tree as soon
+as possible. For now, they can be found on my overlay:
+
+http://overlay.rafaelmartins.eng.br/
+
+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 this to /etc/portage/package.keywords: ::
+
+    app-portage/g-octave **
+
+The live ebuild is only recommended for who want to help testing new
+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): ::
+
+    app-portage/g-octave ~x86
+
+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): ::
+    
+    $ hg clone http://hg.rafaelmartins.eng.br/g-octave/
+
+The release tarballs can be found here:
+
+http://files.rafaelmartins.eng.br/distfiles/g-octave/
+
+
+Configuring g-Octave
+--------------------
+
+If you installed g-Octave correctly, you should find a configuration file
+at */etc/g-octave.cfg*.
+
+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
+file.
+
+
+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: ::
+    
+    # g-octave --sync
+
+
+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*.
+
+You can use something like this command: ::
+    
+    # echo 'PORTDIR_OVERLAY="/path/to/your/overlay ${PORTDIR_OVERLAY}"' >> /etc/make.conf
+
+
+Installing packages
+-------------------
+
+You can list all the available packages using this command: ::
+    
+    # g-octave --list
+
+or ::
+    
+    # g-octave -l
+
+To install a package, use: ::
+    
+    # g-octave packagename
+
+or ::
+    
+    # g-octave packagename-version
+
+For example: ::
+    
+    # g-octave control-1.0.11
+
+g-octave command tool supports some options for the installation of
+packages:
+    
+``-a`` or ``--ask``
+    Ask before install the package
+``-p`` or ``--pretend``
+    Only pretend the installation of the package
+
+You can get some information about the package using this command: ::
+
+    # emerge --info packagename
+
+or ::
+    
+    # emerge -i packagename
+
+
+Uninstalling packages
+---------------------
+
+You can uninstall packages using this command: ::
+
+    # emerge --unmerge packagename
+
+or ::
+    
+    # emerge -C packagename-version
+
+The options ``--ask`` and ``--verbose`` are also supported.