Documented most of the stuff, but still need to make the Twitter (and others) appear in the index

HACKING

@@ -3,7 +3,7 @@ Mitter Hacking Guidelines
 =========================
 
 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 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:
 

README

@@ -9,19 +9,20 @@ networks.
 
 Options
 =======
-To get a list of options Mitter support, you can call it with 
+To get a list of options Mitter support, you can call it with ``mitter
-``mitter --help``. Along with the default options, you'll get options
+--help``. Along with the default options, you'll get options for each
-for each interface and network.
+interface and network.
 
 Config file
 -----------
-Mitter saves its options in a config file in your home directory,
+Mitter saves its options in a config file in your home directory, called
-called ``.mitter.ini``. Some options, not displayed in the command
+``.mitter.ini``. Some options, not displayed in the command line options, are
-line options, are available there. Be careful when changing those
+available there. Be careful when changing those options or Mitter may stop
-options or Mitter may stop working.
+working. Documentation about those options is available in the beginning of
+the module and should be available with the generated documentation.
 
-In any case, if things don't seem to be working, you can remove this
+In any case, if things don't seem to be working, you can remove this file and
-file and Mitter will ask the necessary options to work again.
+Mitter will ask the necessary options to work again.
 
 Networks
 ========
@@ -29,50 +30,52 @@ As for version 1.0, Mitter supports Twitter.
 
 Interfaces
 ==========
-As for version 1.0, Mitter have the following interfaces: PyGTK, TTY,
+As for version 1.0, Mitter have the following interfaces: PyGTK, TTY, Cmd,
-Cmd, Zork.
+Zork.
 
 Choosing Interfaces
 -------------------
-If you want to chose a specific interface, you can use the ``-i``
+If you want to chose a specific interface, you can use the ``-i`` option,
-option, followed by the interface name.
+followed by the interface name. Once you have chose an interface, Mitter will
+keep opening it every time it runs. To change to another interface, use the
+``-i`` option again.
 
 PyGTK
 -----
-PyGTK is a graphical interface, which uses the GTK toolkit. To be
+PyGTK is a graphical interface, which uses the GTK toolkit. To be used, it
-used, it requires that PyGTK is installed in your system. If you don't
+requires that the PyGTK module is installed in your system. If you don't have
-have PyGTK, Mitter will switch to another interface that doesn't
+PyGTK, Mitter will switch to another interface that doesn't require it.
-require it.
 
 TTY
 ---
-TTY is a text interface, used to display the updates. It does not
+TTY is a text interface, used to display the updates. It does not offer any
-offer any interactivity. You can use it to do automated updates
+interactivity. You can use it to do automated updates without user
-without user intervention or to simply retrieve the current messages.
+intervention or to simply retrieve the current messages.
 
 Cmd
 ---
-CMD is a text interface, with a command line. It offers some smart
+CMD is a text interface, with a command line. It will display the messages in
-behaviour, like retrieving new messages when there is no option and
+a numbered list and most of options related to those messages will require the
-starting an update when the command is not recognized.
+message number. It also have 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
+Zork is another text interface, but works a little bit slowly than the Cmd
-Cmd interface. Instead of displaying all the messages at once, Zork
+interface. Instead of displaying all the messages at once and requiring that
-displays message by message, requiring the user to jump to the next
+you select message by their numbers, Zork displays message by message,
-message. It offers a fine-grained control to which message to reply,
+requiring the user to jump to the next message. It offers a fine-grained
-at the expense of few commands.
+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
+Mitter uses Python default module loading to find interfaces. It works like
-means: It will search modules starting with the current directory,
+this: It will search modules starting with the current directory, then the
-then the global system path. When installed via ``setup.py`` or
+global system path. When installed via ``setup.py`` or ``easy_install``,
-``easy_install``, interfaces will be installed in the global system
+interfaces will be installed in the global system directory; if you don't want
-directory; if you don't want to install Mitter, you can run it in the
+to install Mitter, you can run it in the command line, just be sure to be in
-command line, just be sure to be in the main ``mitter`` directory
+the main ``mitter`` directory before call it.
-before call it.
 
 Suggestions? Bugs?
 ==================

docs/docs.rst

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

docs/index.rst

@@ -14,6 +14,8 @@ User Documentation
    INSTALL
    HACKING
 
+   twitter
+
 
 Developer Documentation:
 

mitterlib/network/__init__.py

@@ -28,6 +28,24 @@ _log = logging.getLogger('mitterlib.network.Networks')
 # List of files that are not networks
 SKIPPABLES = ('__init__.py', 'networkbase.py')
 
+"""The network manager, besides managing the other networks and their options,
+have the following options:
+
+*timeout*
+  Timeout for requests, in seconds. This value is (or should) be used to all
+  networks. Default value is '120'.
+
+*save_count*
+  Number of operations till the configuration file is saved again.  Most
+  networks will save their status in the config file, but not request it to be
+  saved immediately (nor should they, 'cause they can save a weird state in
+  case the next network causes Mitter to crash or something related.) A value
+  of 0 means the Network Manager will save the config file after each round of
+  requests to all networks (failing or succeding); for devices that use flash
+  drives as storage, it's recommended some large value (since those devices
+  have a defined number of writes as lifetime.) Default is '5'.
+"""
+
 #--------------------------------------------------------------------
 # Helper functions
 #--------------------------------------------------------------------
@@ -144,7 +162,6 @@ class Networks(object):
         return result
 
     def options(self):
-        """Request all networks to add their options."""
         for shortcut in self.networks:
             conn = self.networks[shortcut]
             conn.options(self._options)

mitterlib/network/networkbase.py

@@ -184,24 +184,31 @@ class NetworkBase(object):
     retrieve information from the network. It's a list of dictionaries,
     containing:
 
-    * *name*: Name of the option, used in ConfigOpt (for the name in the
+    *name*
+      Name of the option, used in ConfigOpt (for the name in the
       config file and to access it through the options variable);
 
-    * *flags*: The list of command line options for this option (as in
+    *flags*
+      The list of command line options for this option (as in
       OptParse);
 
-    * *prompt*: The prompt to be used by interfaces when requesting the
+    *prompt*
+      The prompt to be used by interfaces when requesting the
       variable;
 
-    * *help*: Description for the value; it's used by ConfigOpt to show the
+    *help*
+      Description for the value; it's used by ConfigOpt to show the
       description of the paramater in the command line options and can be used
       by interfaces to show tooltips about the field;
 
-    * *type*: The type of the option; valid values are:
+    *type*
+      The type of the option; valid values are:
 
-      * 'str': A string;
+        **str**
+          A string;
 
-      * 'passwd': Password; string, but interfaces should hide the information
+        **passwd**
+          Password; string, but interfaces should hide the information
           if possible.
     """
 

mitterlib/network/twitter.py

@@ -43,6 +43,39 @@ except ImportError:
     # Fallback to SimpleJSON
     import simplejson as json
 
+"""
+The Twitter network layer have the following options:
+
+*last_tweet*
+  Last tweet seen in the home timeline request. It's used to not request the
+  whole timeline again. Usually, it should not be manually changed. Starts
+  with no value, meaning it will request only the first page; after that, it
+  will requests all tweets, no matter how many pages it is necessary, since
+  the last seen tweet.
+
+*last_reply*
+  Last reply seen in the replies timeline. Works exactly the same as
+  *last_tweet*, but with replies timeline.
+
+*server_url*
+  URL for the non-secure server. Can include any paths. Default value is
+  'http://api.twitter.com/1'.
+
+*secure_server_url*
+  URL for the secure server. Can include any paths. Default value is
+  'https://api.twitter.com/1'.
+
+*threshold*
+  Threshold for not requesting the next page. If the number of returned
+  elements is below this number, the module will not request the next page.
+  This is due the way Twitter uses its cache: In a normal operation, any page
+  that have less than the default 20 elements per page can be considered the
+  last page; due the caching policy Twitter uses, some pages will have less
+  than those 20 elements (it first retrieves the 20 elements, then checks if
+  there are any deleted elements -- if there are, those are removed but no new
+  elements are added to the result.) Default value is '16' (80% of a full
+  page.)
+"""
 # ----------------------------------------------------------------------
 # I18n bits
 # ----------------------------------------------------------------------

mitterlib/ui/ui_pygtk.py

@@ -36,6 +36,35 @@ from mitterlib.ui.helpers.image_helpers import find_image
 from mitterlib.constants import gpl_3, version
 from mitterlib.ui.helpers import timesince
 
+"""
+PyGTK interface internal options:
+
+*width*
+  Width of the main window, in pixels. Default value is '450', but this value
+  is saved when Mitter is closed and reloaded when it's run again.
+
+*height*
+  Height of the main window, in pixels. Default value is '300' but it is saved
+  when Mitter is closed and reloaded when it's run again.
+
+*position_x*
+  X position of the main window. Default value is '5' but it is saved when
+  Mitter is closed and reloaded when it's run again.
+
+*position_y*
+  Y position of the main window. Default value is '5' but it is saved when
+  Mitter is closed and reloaded when it's run again.
+
+*link_colour*
+  Colour for displaying links. Default value is 'blue'. You can use valid X11
+  colour names or hex-triplets (as used in HTML, e.g., #0000ff. -- you need to
+  include the hash in those cases.)
+
+*spell_check*
+  Boolean indicating if spell checker is enabled. Mitter will try to activate
+  it the first time it's run, but it requires Aspell and its Python bindings. 
+"""
+
 # Constants
 
 _log = logging.getLogger('ui.pygtk')
@@ -1482,15 +1511,16 @@ class Interface(object):
                 default=5,
                 conflict_group='interface',
                 is_cmd_option=False)
-        options.add_option(
+        # TODO: Should we use this, anyway?
-                group=self.NAMESPACE,
+        #options.add_option(
-                option='max_status_display',
+        #        group=self.NAMESPACE,
-                help='Maximum number of elements to keep internally',
+        #        option='max_status_display',
-                type='int',
+        #        help='Maximum number of elements to keep internally',
-                metavar='MESSAGES',
+        #        type='int',
-                default=60,
+        #        metavar='MESSAGES',
-                conflict_group='interface',
+        #        default=60,
-                is_cmd_option=False)        # TODO: Should it be config only?
+        #        conflict_group='interface',
+        #        is_cmd_option=False)        # TODO: Should it be config only?
         options.add_option(
                 group=self.NAMESPACE,
                 option='link_colour',