Beginning of the migration to reST documentation

3 files changed, 0 insertions, 185 deletions

diff --git a/doc/en/dev/contributing.txt b/doc/en/dev/contributing.txt
deleted file mode 100644
index 6dbda93e..00000000
--- a/doc/en/dev/contributing.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-Contributing
-============
-
-Conventions
------------
-
-We don’t have a strict set of conventions, but you should respect PEP8 mostly
-(e.g. 4 spaces, class names in CamelCase and methods lowercased with
-underscores) except if it means less-readable code (80 chars is often a hassle,
-and if you look inside poezio you’ll see lots of long lines, mostly because of
-strings).
-
-
-As explained in the link:./overview.html[overview], “global” code goes in
-_core.py_, tab-related code goes in _tabs.py_, and ui-related code goes in
-_windows.py_. There are other modules (e.g. xhtml.py) but they do not matter
-for the application as a whole.
-
-Commit guidelines
------------------
-
-Commits _should_ have a meaninful title (first line), and _may_ have a detailed
-description below. There are of course exceptions (for example, a single-line
-commit that takes care of a typo right behind a big commit does not need to
-say “fix a typo ("azre" → "are") in toto.py line 45454", since the metainfos
-already take care of that.), but if you do not have commit access on the
-poezio trunk, you can still reset and commit again.
-
-
-Try to do atomic commits: since git is a DVCS, it doesn’t hurt to git add -p
-and split the commit into several meaningful small commits ; on the contrary,
-it helps to track the changes on different levels.
-
-
-If you have a conflict, solve it with rebase and not merge if the fast-forwards
-do not resolve it automatically in your case. This helps to avoid creating
-useless merges (and polluting the commit history) when none is needed.
-
-.Basic case
-==========================
-
-  git fetch origin
-  git rebase origin/master
-  git push origin master
-
-==========================
-
-If your commit is related to an issue on
-link:https://dev.louiz.org/project/poezio/bugs[our tracker] (or fixes such an
- issue), you can use “Fixes #BUGID” or “References #BUGID” to help with the
- tracking.
-
-
-Getting your code into poezio
------------------------------
-
-If you have code you want to contribute, you can:
-
-* Give us a patch and a description of what it does
-* Give us a link to a _git_ repo from which we can pull
-
-The code is of course reviewed and tested a bit, but we trust the contributors
-to submit good code. If we can’t integrate the given code into poezio (if it
-crashes or has some issues), if the size is small, we may tweak it ourselves
-and integrate it, and if not, you are of course free to take our advice into
-account and submit it again.
-
-
-If you have already submitted some code and plan to do more, you can ask us
- direct commit access on the main repo.
-
diff --git a/doc/en/dev/index.txt b/doc/en/dev/index.txt
deleted file mode 100644
index 17ca42d6..00000000
--- a/doc/en/dev/index.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-Development
-===========
-
-This section of the documentation is here to provide a quickstart for someone
-willing to start hacking poezio.
-
-* link:overview.html[Overview]
-* link:contributing.html[Contributing]
diff --git a/doc/en/dev/overview.txt b/doc/en/dev/overview.txt
deleted file mode 100644
index 7f9f9445..00000000
--- a/doc/en/dev/overview.txt
+++ /dev/null
@@ -1,106 +0,0 @@
-Overview
-========
-
-NOTE: This is not an introduction to XMPP, but to poezio
-
-
-Global overview
----------------
-
-Poezio is an application that has three main layers, mostly separated in three
-different python modules: _core_, _tabs_, and _windows_. An UML diagram of
-Poezio would be inneficient, cluttered, or incomplete, so there is none, if
-that bugs you.
-
-image::../../images/layers.png["The application layers", title="Layers"]
-
-_Core_ is mostly a “global” object containing the state of the application at
-any time, it contains the global commands, the xmpp event handlers, the list
-of open tabs, etc. Most objects in poezio have a self.core attribute
-referencing the _Core_ (it’s a singleton, so there is never more than one
-instance). _Core_ also contains the main loop of the application, which then
-dispatchs the I/O events (keypress) to the appropriate methods.
-
-
-But the main loop is not the most important thing in poezio; because it is an
-IM client, it is essentially event-driven. The event part is handled by
-SleekXMPP, which is the library we chose after moving away from xmpppy.
-
-
-_Tabs_ are the second layer of poezio, but the first dealing with the UI: each
-_Tab_ is a layout of several _windows_, it contains tab-specific commands,
-tab-specific keybinds, and it has methods in order for core to
-interact with it, and some methods are only proxies for the methods of a
-_window_
-
-Example scenario: If someone presses the key PageUp, then Core will call the
-appropriate method on the current _Tab_, which will in turn, if it implements the
-method (inherited empty from the Tab class), call a scrolling method from the
-appropriate _window_.
-
-All tabs types inherit from the class _Tab_, and the _Tabs_ featuring
-chat functionnality will inherit fro _ChatTab_ (which inherits from _Tab_).
-
-Examples of _Tabs_: MUCTab, XMLTab, RosterTab, MUCListTab, etc…
-
-Event handlers
---------------
-
-The events handlers are registered right at the start of poezio, and then
-when a matching stanza is received, the handler is called in a separate thread
-from the main loop. The handlers are in _Core_, and then they call the
-appropriate methods in the corresponding _tabs_.
-
-Example scenario: if a message is received from a MUC, then the _Core_ handler
-will identify the _Tab_, and call the relevant handler from this _Tab_, this tab
-will in turn, add the message to the buffer, which will then add it to the
-relevant _windows_.
-
-NOTE: All the _windows_ that deal with received or generated text are linked
-to a _text_buffer_, in order to rebuild all the display lines from the
-sources if necessary. This also enables us to have several _windows_
-presenting the same text, even if they are not of the same size and layout.
-
-
-Commands and completion
------------------------
-
-Commands are quite straightforward: those are methods that take a string as a
-parameter, and they do stuff.
-
-From an user point of view, the methods are entered like that:
-
-==================================
-
-  /command arg1 arg2
-
-or
-
-  /command "arg1 with spaces" arg2
-
-==================================
-
-However, when creating a command, you wil deal with _one_ str, no matter what.
-There are utilities to deal with it (common.shell_split), but it is not always
-necessary. Commands are registered in the _commands_ dictionnary of a tab
-structured as key (command name) -> tuple(command function, help string, completion).
-
-
-Completions are a bit tricky, but it’s easy once you get used to it:
-
-They take an _Input_ (a _windows_ class) as a parameter, named the_input
-everywhere in the sources. To effectively have a completion, you have to call
-_the_input.auto_completion()_ at the end of the function.
-
-*the_input.auto_completion(completion_list, after='', quote=True)*:
-Set the input to iterate over _completion_list_ when the user hits tab, insert
-_after_ after the completed item, and surround the item with double quotes or
-not.
-
-There is no method to find the current argument in the input (although the
-feature is planned), so you have to assume the current argument is the last,
-and guess it by splitting the string an checking for end-space.
-
-You can look for examples in the sources, all the possible cases are
-covered (single-argument, complex arguments with spaces, several arguments,
-etc…)