Documentation

HACKING

@@ -0,0 +1,152 @@
+=======
+HACKING
+=======
+
+How to hack Mitter
+==================
+First of all, Mitter is a Python project and it tries to follow PEP8_
+as close as possible.  Sometimes, we fail, but we try to adhere to it
+as much as possible.  The Google Guidelines_ for Python are a good
+summary about it, although we don't follow all their recommendations:
+
+- We use PyFlakes instead of Pychecker. PyFlakes seems to be better in
+  finding unused imports. As usual, some files don't adhere to it,
+  mostly helper tools (Sphinx and the helper PEP8 checker, for
+  example.)
+- Exceptions do not start with an Error class. Each module should have
+  its own Exception, e.g. NetworkError and all other exceptions
+  should use that as base,  e.g. ::
+
+     class UnreachableNetworkError(NetworkError):
+
+- Function parameters do not need to follow the break lines, pointed,
+  but must follow the 80 columns rule.
+
+
+Documentation
+=============
+Also, all documentation (including this file!) follows the Sphinx_
+format (ReSTructured_ format). This includes docstrings and external
+files.
+
+Creating Interfaces
+===================
+There is a couple of things you should take care when creating your
+own interface.
+
+Naming and Location
+-------------------
+Your file must have the prefix "ui\_". It must be installed in the
+``mitterlib/ui`` directory.
+
+class Interface
+---------------
+Inside your module, there should be at least one class called
+``Interface``. It may inherit any other class (or ``object`` in case
+you don't need anything).
+
+__init__(self, connection, options)
+-----------------------------------
+The initialization will receive two parameters:
+- connection: the network connection. Your interface will request any
+  network data with that object. You can check the ``Networks`` object
+  in the ``mitterlib/network/__init__.py`` for methods there (or read
+  the Sphinx documentation generated about it.)
+- options: It's a ConfigOpt_ object, with all your interface options.
+  Use it for EVERTYHING that you'd hardcode.
+
+__call__(self)
+--------------
+Once Mitter have everything set up, it will call your interface.
+``__call__`` is to interfaces as ``run()`` is to threads.
+
+options(self, options)
+----------------------
+``options`` is a ``@classmethod`` called by Mitter on the setting up
+phase to populate the interface options. To add an option, use the
+``add_option``; if your interface don't have any options, simply
+return. Again, refer to the ConfigOpt_ documentation on how to use it.
+
+Creating Networks
+=================
+Naming and Location
+-------------------
+Network reside in the ``mitterlib/network`` directory. Contrary to
+interfaces, it doesn't require any special prefixes.
+
+Base Class
+----------
+All networks must inherit from the :class:`NetworkBase` object, in
+the module ``networkbase``. There is a couple of method you should
+implement in case you want it to return any data. If the network
+doesn't support some functionality (e.g. reposts), simply don't
+declare the function. :class:`NetworkBase` offers good defaults to
+all functions (basically, returning nothing.)
+
+Base Return Object
+------------------
+Most functions will return a :class:`NetworkData` object. It offers
+an unified data format for every interface, so they don't need to
+worry about each network data. It is wise to create your own
+:class:`NetworkData`, inheriting from it, with its own ``__init__``
+and setting the properties.
+
+Mixing It All
+=============
+
+Creating New Elements
+---------------------
+In case you want to display/add a new element on your interface, you
+need to add the element in :class:`NetworkData` with a default that
+represents it better (for boolean values, set it to False; strings to
+''; numbers to 0 or 0.0). Once your element is there, you can add it
+in the networks (do not ignore other networks that may use that
+information!) and then, finally, use it on your interface.
+
+Creating New Request
+--------------------
+If you want to add a new functionality in the interfaces, you need do
+to a couple of steps:
+
+- First of all, you need to add the method in the :class:`Networks`.
+  Remember that this is the class that the interfaces receive to do
+  all the other calls. If the function doesn't exist there, it won't
+  be call it at all.
+
+- Once the function is available to be called, you need to make it
+  available to the networks. For this, add the function in
+  :class:`NetworkBase` module, so calling it on networks that don't
+  have that method defined yet will still work. In this point, it
+  should return some sort of empty value (empty list, None).
+
+- Finally, add the function on your network. Follow the same name in
+  the :class:`NetworkBase` and you should be fine.
+
+Developer Discussion
+====================
+Mitter have an open developer discussion maillist. Join us on
+Mitter-Dev_ if you have any suggestions/patches/questions.
+
+(We had a massive problem with spammers in the recent days, so the
+list is currently moderated. Your first message needs to be approved
+and, after that, everything should be fine.)
+
+Souce Code Repository
+=====================
+Mitter uses Git for SCM and Gitorious to host it. You can check the
+Mitter_ project there, clone it and hack away! ;)
+
+
+.. _PEP8: http://www.python.org/dev/peps/pep-0008/
+
+.. _Guidelines: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
+
+.. _Sphinx: http://sphinx.pocoo.org/
+
+.. _ReSTRuctured: http://docutils.sourceforge.net/docs/user/rst/quickref.html
+
+.. _ConfigOpt: http://deadbraincells.org/configopt/docs/configopt.html
+
+.. _Mitter-Dev: http://groups.google.com/group/mitter-dev/
+
+.. _Mitter: http://gitorious.org/projects/mitter

INSTALL

@@ -0,0 +1,37 @@
+=======
+INSTALL
+=======
+
+Requirements
+============
+
+Mitter requires Python, at least version 2.5. Version 2.6 should be
+fine. There is no guarantee that it will work with Python 3.0 at this
+point.
+
+For the GTK interface, you'll need PyGTK installed. The minimum
+version is 2.10 and Mitter should work fine with any further version
+in the 2.x series. Again, there is no guarantee that it will work with
+GTK 3.0 when it's released. Also notice that PyGTK is optional and
+Mitter will use it's console interfaces in this case.
+
+Installation
+============
+
+Installation follows the default Python apps install:
+
+Using easy_install
+------------------
+
+You can install using easy_install. To install, simply call
+``easy_install mitter``. It may require root access to install some
+files.
+
+Using setup.py
+--------------
+
+After unpacking the Mitter package, you'll find a ``setup.py`` file.
+To install, call ``python setup.py install`` and it will install
+Mitter in ``/usr/local/bin``. To install in a different directory, use
+the ``--prefix`` parameter. ``python setup.py help`` will show other
+options you can use.

README

@@ -0,0 +1,83 @@
+======
+README
+======
+
+About Mitter
+============
+Mitter is a multi-protocol, multi-interface client for micro-blogging
+sites.
+
+Options
+=======
+To get a list of options Mitter support, you can call it with 
+``mitter --help``. Along with the default options, you'll get options
+for each interface and network.
+
+Config file
+-----------
+Mitter saves its options in a config file in your home directory,
+called ``.mitter.ini``. Some options, not displayed in the command
+line options, are available there. Be careful when changing those
+options or Mitter may stop working.
+
+In any case, if things don't seem to be working, you can remove this
+file and Mitter will ask the necessary options to work again.
+
+Networks
+========
+As for version 1.0, Mitter supports Twitter.
+
+Interfaces
+==========
+As for version 1.0, Mitter have the following interfaces: PyGTK, TTY,
+Cmd, Zork.
+
+Choosing Interfaces
+-------------------
+If you want to chose a specific interface, you can use the ``-i``
+option, followed by the interface name.
+
+PyGTK
+-----
+PyGTK is a graphical interface, which uses the GTK toolkit. To be
+used, it requires that PyGTK is installed in your system. If you don't
+have PyGTK, Mitter will switch to another interface that doesn't
+require it.
+
+TTY
+---
+TTY is a text interface, used to display the updates. It does not
+offer any interactivity. You can use it to do automated updates
+without user intervention or to simply retrieve the current messages.
+
+Cmd
+---
+CMD is a text interface, with a command line. It offers some smart
+behaviour, like retrieving new messages when there is no option and
+starting an update when the command is not recognized.
+
+Zork
+----
+Zork is another text interface, but works a little bit slowly than the
+Cmd interface. Instead of displaying all the messages at once, Zork
+displays message by message, requiring the user to jump to the next
+message. It offers a fine-grained control to which message to reply,
+at the expense of few commands.
+
+How Mitter Finds Interfaces
+---------------------------
+Mitter uses Python default module loading to find interfaces. This
+means: It will search modules starting with the current directory,
+then the global system path. When installed via ``setup.py`` or
+``easy_install``, interfaces will be installed in the global system
+directory; if you don't want to install Mitter, you can run it in the
+command line, just be sure to be in the main ``mitter`` directory
+before call it.
+
+Suggestions? Bugs?
+==================
+If you have any suggestions or think your found a bug, don't keep it
+to yourself! We have an open bug tracking with Google Code open to the
+public. Be sure to check there and drop your opinion:
+
+http://code.google.com/p/mitter/

docs/HACKING.rst

@@ -0,0 +1 @@
+../HACKING

docs/INSTALL.rst

@@ -0,0 +1 @@
+../INSTALL

docs/README.rst

@@ -0,0 +1 @@
+../README

docs/docs.rst

@@ -0,0 +1,4 @@
+Documentation
+=============
+
+  HACKING

docs/index.rst

@@ -5,7 +5,17 @@
 Welcome to Mitter's documentation!
 ==================================
 
-Contents:
+User Documentation
+
+.. toctree::
+   :maxdepth: 1
+
+   README
+   INSTALL
+   HACKING
+
+
+Developer Documentation:
 
 .. toctree::
    :maxdepth: 2