From bd8d38d711e15d42ac8e797723af5242e4c3f4fb Mon Sep 17 00:00:00 2001 From: mathieui Date: Mon, 8 Apr 2013 18:52:35 +0200 Subject: Beginning of the migration to reST documentation --- doc/source/dev/common.rst | 8 +++ doc/source/dev/events.rst | 142 ++++++++++++++++++++++++++++++++++++++++ doc/source/dev/index.rst | 19 ++++++ doc/source/dev/plugin.rst | 41 ++++++++++++ doc/source/dev/sleek.rst | 16 +++++ doc/source/dev/timed_events.rst | 17 +++++ 6 files changed, 243 insertions(+) create mode 100644 doc/source/dev/common.rst create mode 100644 doc/source/dev/events.rst create mode 100644 doc/source/dev/index.rst create mode 100644 doc/source/dev/plugin.rst create mode 100644 doc/source/dev/sleek.rst create mode 100644 doc/source/dev/timed_events.rst (limited to 'doc/source/dev') diff --git a/doc/source/dev/common.rst b/doc/source/dev/common.rst new file mode 100644 index 00000000..f9ee7c77 --- /dev/null +++ b/doc/source/dev/common.rst @@ -0,0 +1,8 @@ +Common operations documentation +=============================== + +.. automodule:: common + :members: + :undoc-members: + + diff --git a/doc/source/dev/events.rst b/doc/source/dev/events.rst new file mode 100644 index 00000000..c2aa4036 --- /dev/null +++ b/doc/source/dev/events.rst @@ -0,0 +1,142 @@ +Event Index +=========== + +The following events are poezio-only events, for SleekXMPP events, check out +`their index `_. + +.. glossary:: + :sorted: + + muc_say + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered whenever the user sends a message to a :py:class:`~tabs.MucTab`. + + muc_say_after + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.MucTab` source + + Same thing than :term:`muc_say`, but after XHTML generation of the body, if needed. + This means you must not insert any colors in the body in the handler, since + it may lead to send invalid XML. This hook is less safe than ``muc_say`` and + you should probably not need it. + + private_say + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.PrivateTab` source + + Triggered whenever the user sends a message to a :py:class:`~tabs.PrivateTab`. + + private_say_after + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.PrivateTab` source + + Same thing than :term:`private_say`, but after XHTML generation of the body, if needed. + This means you must not insert any colors in the body in the handler, since + it may lead to send invalid XML. This hook is less safe than :term:`private_say` and + you should probably not need it. + + conversation_say + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.ConversationTab` source + + Triggered whenever the user sends a message to a :py:class:`~tabs.ConversationTab`. + + conversation_say_after: + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.ConversationTab` source + + Same thing than :term:`conversation_say`, but after XHTML generation of the body, if needed. + This means you must not insert any colors in the body in the handler, since + it may lead to send invalid XML. This hook is less safe than :term:`conversation_say` and + you should probably not need it. + + muc_msg + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when a message is received in a :py:class:`~tabs.MucTab`. + + private_msg + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.PrivateTab` source + + Triggered when a message is received in a :py:class:`~tabs.PrivateTab`. + + conversation_msg + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.ConversationTab` source + + Triggered when a message is received in a :py:class:`~tabs.ConversationTab`. + + conversation_chatstate + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.ConversationTab` source + + Triggered when a chatstate is received in a :py:class:`~tabs.ConversationTab`. + + muc_chatstate + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when a chatstate is received in a :py:class:`~tabs.MucTab`. + + private_chatstate + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`PrivateTab ` source + + Triggered when a chatstate is received in a :py:class:`~tabs.PrivateTab`. + + normal_presence + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **resource:** :py:class:`Resource ` that emitted the :py:class:`~sleekxmpp.Presence` + + Triggered when a presence is received from a contact. + + muc_presence + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when a presence is received from someone in a :py:class:`~tabs.MucTab`. + + send_normal_presence + - **presence:** :py:class:`~sleekxmpp.Presence` sent + + Triggered when before poezio sends a new :py:class:`~sleekxmpp.Presence` stanza. + + muc_join + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when an user joins a :py:class:`~tabs.MucTab` + + muc_ban + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when an user from a :py:class:`~tabs.MucTab` + gets banned. + + muc_kicked + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when an user from a :py:class:`~tabs.MucTab` + gets kicked. + + muc_nickchange + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when an user in a :py:class:`~tabs.MucTab` changes + his nickname. + + ignored_private + - **message**:py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.PrivateTab` source + + Triggered when a private message (that goes in a :py:class:`~tabs.PrivateTab`) + is ignored automatically by poezio. + + **tab** is always ``None``, except when a tab has already been opened. diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst new file mode 100644 index 00000000..7498e0e8 --- /dev/null +++ b/doc/source/dev/index.rst @@ -0,0 +1,19 @@ +.. Poezio Plugin development documentation master file, created by + sphinx-quickstart on Mon Mar 4 23:39:07 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Development documentation +========================= + +Contents: + +.. toctree:: + :maxdepth: 2 + + plugin + events + timed_events + common + sleek + diff --git a/doc/source/dev/plugin.rst b/doc/source/dev/plugin.rst new file mode 100644 index 00000000..7978a5e9 --- /dev/null +++ b/doc/source/dev/plugin.rst @@ -0,0 +1,41 @@ +Plugin API documentation +======================== + +.. module:: plugin + +.. autoclass:: BasePlugin + :members: init, cleanup, api, core + + .. method:: init(self) + + Method called at the creation of the plugin. + + Do not override __init__ and use this instead. + + .. method:: cleanup(self) + + Method called before the destruction of the plugin. + + Use it to erase or save things before the plugin is disabled. + + .. attribute:: core + + The Poezio :py:class:`~Core` object. Use it carefully. + + .. attribute:: api + + The :py:class:`~PluginAPI` instance for this plugin. + + +Each plugin inheriting :py:class:`~BasePlugin` has an ``api`` member variable, which refers +to a :py:class:`~PluginAPI` object. + +The :py:class:`~PluginAPI` object is an a interface through which the :py:class:`~BasePlugin` +(and inheritors) *should* go to interact with poezio. If it is not sufficient, then the ``core`` +member can be used. + +.. autoclass:: PluginAPI + :members: + :undoc-members: + + diff --git a/doc/source/dev/sleek.rst b/doc/source/dev/sleek.rst new file mode 100644 index 00000000..7baf5b29 --- /dev/null +++ b/doc/source/dev/sleek.rst @@ -0,0 +1,16 @@ +SleekXMPP classes +================= + +.. module:: sleekxmpp + +.. autoclass:: Message + :members: + +.. autoclass:: Presence + :members: + +.. autoclass:: Iq + :members: + + + diff --git a/doc/source/dev/timed_events.rst b/doc/source/dev/timed_events.rst new file mode 100644 index 00000000..a2c96912 --- /dev/null +++ b/doc/source/dev/timed_events.rst @@ -0,0 +1,17 @@ +Timed events documentation +========================== + +.. automodule:: timed_events + +.. autoclass:: TimedEvent + + .. automethod:: __init__ + .. automethod:: has_timed_out + .. automethod:: change_date + .. automethod:: add_delay + + +.. autoclass:: DelayedEvent + + .. automethod:: __init__ + -- cgit v1.2.3