diff options
Diffstat (limited to 'doc/en/dev')
| -rw-r--r-- | doc/en/dev/contributing.txt | 71 | ||||
| -rw-r--r-- | doc/en/dev/index.txt | 8 | ||||
| -rw-r--r-- | doc/en/dev/overview.txt | 106 |
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…) |