Documented all options now

CHEAT-CODES

@@ -0,0 +1,124 @@
+========================
+Hidden options in Mitter
+========================
+
+Mitter have some options that are not completely visible to the user.
+Those options reside in the config file (usually ``.mitter.ini`` in
+the user home directory) and can affect the application behaviour or
+appearance.
+
+Config Format
+=============
+Before changing anything, you must be aware of the format of the
+config file. It's a format called "INI file", where options are
+separated by sections. Sections have square brackets around them while
+options have an equal sign separating the option name and the option
+value. Here is a small example, with a section called *Section* and an
+option called *option* with the value *value*::
+
+  [Section]
+  option = value
+
+
+Network Manager
+===============
+The Network Manager is responsible for managing all the network layers
+and provide a single point of access to them for the interfaces. The
+network manager uses the ``NetworkManager`` section:
+
+*timeout*
+  Timeout for requests, in seconds. This value is (or should) be
+  used by all networks. If a quests takes longer than those seconds,
+  it will be canceled and the result, a failure. 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: In case
+  something wrong happens, the state in the config file will not be
+  reasonable when mitter is run again.) 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 storage devices have a lifetime based on the number
+  of writes.) Default is '5'.
+
+Twitter
+=======
+Twitter is the most famous micro-blogging website and the original
+network supported by Mitter. It have the following options:
+
+*https*
+  A boolean value (can accept either "True" or "False" as values)
+  indicating that HTTPS (secure HTTP) should be used.
+
+*server_url*
+  Points to the URL to be used for insecure requests. If *https* is
+  False, all requests will go to this URL.
+
+*secure_server_url*
+  Points to the URL to be used for secure requests. If *https* is
+  True, all requests will go to this URL.
+
+*last_tweet*
+  Twitter supports a "since_id" on requests, allowing less (or more)
+  requests to be made to retrieve information since the last time
+  the user saw their messages. Mitter uses it on every request to
+  get just the new messages instead of everything (and not miss any
+  tweets in case you leave Mitter close for awhile.) If this value
+  is does not exist in the config file, Mitter will request only the
+  first page and update this values.
+ 
+*last_reply*
+  Works exactly like *last_tweet*, except for replies.
+
+*message_threshold*
+  Twitter uses 20 messages per page, but due their caching mecanism,
+  some pages may have less than 20 message on each page (in other
+  words, it works like this: they have the result pages set already,
+  but when you request something, they finally check if there are
+  deleted tweets in it and, if there are any, they are removed
+  there, but no new messages are added.) If the number of messages
+  is below the threshold, Mitter will not request the next page. The
+  default value is '16', or 80% of the default page size.
+
+PyGTK
+=====
+PyGTK is the default graphical interface. It have the following
+options:
+
+*refresh_interval*
+  The refresh interval to check for new messages, in minutes.
+  Default value is '5'.
+
+*statusicon*
+  Display the status icon in the systray. Default is True.
+
+*width*
+  Window width, in pixels. It stars with 450, but it's updated when
+  Mitter closes.
+
+*height*
+  Window height, in pixels. It starts with 300, but it's updated
+  when Mitter closes.
+
+*position_x*
+  Horizontal position of the window in the screen. It starts with 5,
+  but it's saved when Mitter closes.
+
+*position_y*
+  Vertical position of the window in the screen. It starts with 5,
+  but it's saved when Mitter closes.
+
+*link_colour*
+  Color to be used when displaying links. Default value is 'blue';
+  it accepts any X11 named colours or hex triplests (like the ones
+  used in HTML.)
+
+*spell_check*
+  Boolean indicating if the spell checker should be used. To have
+  spell checkers enabled, you must have PyAspell installed, so it's
+  checked once and, if PyAspell is not installed, will be set as
+  False and not checked again. If you install PyAspell after Mitter
+  is run the first time, you must manually update this value.

docs/CHEAT-CODES.rst

@@ -0,0 +1 @@
+../CHEAT-CODES

docs/index.rst

@@ -13,8 +13,7 @@ User Documentation
    README
    INSTALL
    HACKING
-
+   CHEAT-CODES
-   twitter
 
 
 Developer Documentation:

mitterlib/network/__init__.py

@@ -28,24 +28,6 @@ _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 storage
-  devices have a lifetime based on the number of writes.) Default is '5'.
-"""
-
 #--------------------------------------------------------------------
 # Helper functions
 #--------------------------------------------------------------------
@@ -162,6 +144,10 @@ class Networks(object):
         return result
 
     def options(self):
+        """Add the options for all networks and the network manager options
+        itself."""
+        # Remember that, in case you add or remove any options here, you
+        # should also update the CHEAT-CODES file.
         for shortcut in self.networks:
             conn = self.networks[shortcut]
             conn.options(self._options)

mitterlib/network/twitter.py

@@ -43,39 +43,6 @@ 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
 # ----------------------------------------------------------------------
@@ -313,6 +280,8 @@ class Connection(NetworkBase):
     @classmethod
     def options(self, options):
         """Add options related to Twitter."""
+        # Rememeber to update the CHEAT-CODES file if you add/remove any
+        # options.
         options.add_group(self.NAMESPACE, 'Twitter network')
         options.add_option('-s', '--no-https',
                 group=self.NAMESPACE,

mitterlib/ui/ui_pygtk.py

@@ -37,34 +37,6 @@ 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
 
@@ -1460,6 +1432,8 @@ class Interface(object):
     @classmethod
     def options(self, options):
         """Add the options for this interface."""
+        # Remember to update CHEAT-CODES in case you add or remove any
+        # options.
         options.add_group(self.NAMESPACE, 'GTK+ Interface')
         options.add_option('--refresh-interval',
                 group=self.NAMESPACE,