From d67fbf53301da9fe5463507cd3943cdc8b9dc99d Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Wed, 30 Dec 2009 21:50:04 -0200 Subject: [PATCH] Documentation --- HACKING | 152 +++++++++++++++++++++++++++++++++++++++++++++++ INSTALL | 37 ++++++++++++ README | 83 ++++++++++++++++++++++++++ docs/HACKING.rst | 1 + docs/INSTALL.rst | 1 + docs/README.rst | 1 + docs/docs.rst | 4 ++ docs/index.rst | 12 +++- 8 files changed, 290 insertions(+), 1 deletion(-) create mode 100644 HACKING create mode 100644 INSTALL create mode 100644 README create mode 120000 docs/HACKING.rst create mode 120000 docs/INSTALL.rst create mode 120000 docs/README.rst create mode 100644 docs/docs.rst diff --git a/HACKING b/HACKING new file mode 100644 index 0000000..4d4de69 --- /dev/null +++ b/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 diff --git a/INSTALL b/INSTALL new file mode 100644 index 0000000..d4a4ae0 --- /dev/null +++ b/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. diff --git a/README b/README new file mode 100644 index 0000000..fe1aa78 --- /dev/null +++ b/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/ diff --git a/docs/HACKING.rst b/docs/HACKING.rst new file mode 120000 index 0000000..cc8063b --- /dev/null +++ b/docs/HACKING.rst @@ -0,0 +1 @@ +../HACKING \ No newline at end of file diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst new file mode 120000 index 0000000..99d491b --- /dev/null +++ b/docs/INSTALL.rst @@ -0,0 +1 @@ +../INSTALL \ No newline at end of file diff --git a/docs/README.rst b/docs/README.rst new file mode 120000 index 0000000..59a23c4 --- /dev/null +++ b/docs/README.rst @@ -0,0 +1 @@ +../README \ No newline at end of file diff --git a/docs/docs.rst b/docs/docs.rst new file mode 100644 index 0000000..49c58b5 --- /dev/null +++ b/docs/docs.rst @@ -0,0 +1,4 @@ +Documentation +============= + + HACKING diff --git a/docs/index.rst b/docs/index.rst index 8b80155..31f1ad4 100644 --- a/docs/index.rst +++ b/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