Commit bd8d38d7 authored by mathieui's avatar mathieui

Beginning of the migration to reST documentation

parent e5f219d4
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PoezioPlugindevelopment.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PoezioPlugindevelopment.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/PoezioPlugindevelopment"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PoezioPlugindevelopment"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
This diff is collapsed.
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.
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]
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…)
Poezio Documentation
====================
Welcome to the english documentation, here is a list of the available pages.
Available pages
---------------
* link:install.html[Installation]
* link:configure.html[Configuration]
* link:ssl.html[SSL Management]
* link:usage.html[Usage]
* link:themes.html[Theming]
* link:keys.html[Keys]
* link:plugins/index.html[Available Plugins]
* link:misc/index.html[Other topics]
* link:plugins.html[Developing plugins]
* link:dev/index.html[Developing Poezio]
* link:xep.html[Current XEP support]
* link:dev/index.html[Contributing]
Keys
====
This file describes the default keys of poezio and explains how to
configure them.
By default, most keys manipulating the input (where you type your
messages and commands) behave like emacs does.
NOTE: keys are case sensitive. Ctrl-X is not the same than Ctrl-x
Key bindings listing
--------------------
Some key bindings are available only in some tabs, others are global.
Global keys
~~~~~~~~~~~
These keys work in *any* tab.
*Ctrl-n*:: Go to the next tab.
*Ctrl-p*:: Go to the previous tab.
*Alt-number*:: Go to the tab with that number.
*Alt-j*:: Waits for you to type a two-digits number. Go to tab number xx.
*Alt-e*:: Go to the tab with a higher priority (private message >
highlight > message > non-empty input).
*Alt-z*:: Go to the previously selected tab.
*Alt-r*:: Go to the roster tab.
*F7*:: Shrink the information buffer.
*F8*:: Grow the information buffer.
*Ctrl-l*:: Refresh the screen.
*Alt-D*:: Scroll the information buffer up.
*Alt-C*:: Scroll the information buffer down.
Input keys
~~~~~~~~~~
These keys concern only the inputs.
NOTE: The clipboard is common to all inputs. This lets you cut a text
from one input to paste it into an other one.
*Ctrl-a*:: Move the cursor to the beginning of line.
*Ctrl-e*:: Move the cursor to the end of line.
*Ctrl-u*:: Delete the text from the start of the input until the cursor
and save it to the clipboard.
*Ctrl-k*:: Delete the text from the cursor until the end of the input
and save it to the clipboard.
*Ctrl-y*:: Insert the content of the clipboard at the cursor position.
*Ctrl-Enter*:: Insert a line break. Since the input is only one line,
the line break is represented by the character _|_ in it but will be
sent as the real _\n_ character.
Chat tab input keys
~~~~~~~~~~~~~~~~~~~~~
These keys work in any conversation tab (MultiUserChat, Private or
Conversation tabs).
*Key Up*:: Use the previous message from the message history.
*Key Down*:: Use the next message from the message history.
*Page Up*:: Scroll up in the conversation by x lines, where x is the
height of the conversation window - 1.
*Page Down*:: Like Page Up, but down.
*Ctrl-b*:: Go one line up in the buffer.
*Ctrl-f*:: Go one line down in the buffer.
*Ctrl-s*:: Go half a screen up in the buffer.
*Ctrl-x*:: Go half a screen down in the buffer.
*Alt-/*:: Complete what you’re typing using the "recent" words from the
current conversation, if any.
*Alt-v*:: Move the separator at the bottom of the tab.
*Alt-h*:: Scroll to the separator, if there is one.
MultiUserChat tab input keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These keys work only in the MultiUserChat tab.
*Alt-u*:: Scroll the user list down.
*Alt-y*:: Scroll the user list up.
*Alt-p*:: Scroll to the previous highlight.
*Alt-n*:: Scroll to the next highlight.
*tabulation*:: Complete a nick.
*Ctrl-c*:: Insert xhtml formatting. You have to press Ctrl-c then a character
listed below:
- 1: Red
- 2: Green
- 3: Yellow/Orange
- 4: Blue
- 5: Pink
- 6: Turquoise
- b: Bold
- o: Stop formatting
MultiUserChat List tab input keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These keys work only in the MultiUserChat List tab (obtained with /list <server>).
*Up*:: Go up one row.
*Down*:: Go down one row.
*j*:: Join the MultiUserChat currently selected.
*J*:: Join the MultiUserChat currently selected, without giving focus to iuts tab.
*Ctrl-M*:: Join the MultiUserChat currently selected (same as "j").
*PageUp*:: Scroll a page of chats up.
*PageDown*:: Scroll a page of messages down.
Roster tab input keys
~~~~~~~~~~~~~~~~~~~~~
These keys work only in the Roster tab (the tab number 0).
*/*:: Open a prompt for commands.
*s*:: Start a search on the contacts.
*S*:: Start a (slow) search with approximation on the contacts.
*Alt-u*:: Move the cursor to the next group.
*Alt-y*:: Move the cursor to the previous group.
*Ctrl-c*:: Cancel the input (search or command)
NOTE: The following will not work if you can still write things in the
input (meaning you previously typed _s_ or _/_):
*Space*:: Fold/Unfold the current item.
*Up*:: Move the cursor down one contact.
*Down*:: Move the cursor up one contact.
*o*:: Show the offline contacts.
*PageUp*:: Scroll a page of contacts up.
*PageDown*:: Scroll a page of contacts down.
Data Forms tab keys
~~~~~~~~~~~~~~~~~~~
*Ctrl+y*:: Validate the form, send it and close the tab.
*Ctrl+g*:: Cancel that form (do not send your changes) and close the
tab.
*Up*:: Select the next field.
*Down*:: Select the previous field.
*Right/Left*:: Switch between possible values, in a jid-multi,
list-multi, list-single or text-multi field.
*Space*:: Select that option
MultiUserChat List tab input keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These keys work only in the MultiUserChat List tab (obtained with /list
<server>).
*Up*:: Go up one row.
*Down*:: Go down one row.
*j*:: Join the MultiUserChat currently selected.
*J*:: Join the MultiUserChat currently selected, without giving focus to
iuts tab.
*Ctrl-M*:: Join the MultiUserChat currently selected (same as _j_).
XML tab input keys
~~~~~~~~~~~~~~~~~~
These keys only work in the XML tab (obtained with /xml_tab)
*Ctrl+k*:: Freeze or un-freeze the display in order to have a clear view of
the stanzas.
Key configuration
-----------------
Bindings are keyboard shortcut aliases. You can use them
to define your own keys to replace the default ones.
where _^x_ means _Control + x_
and _M-x_ means _Alt + x_
To know exactly what the code of a key is, just run
==================
python3 src/keyboard.py
==================
And enter any key.
.Turn Alt-i into a tab key (completion, etc)
==================
M-i = ^I
==================
Actions
-------
Mapping actions on keys
~~~~~~~~~~~~~~~~~~~~~~~
One may want to add keyboard shortcuts on actions that were not mapped already
in poezio. To this effect, you can map the keys on actions using the _Key
configuration_ seen in the previous section.
The actions are pseudo-keystrokes, and have to be treated the same way.
They all begin with an underscore to prevent any possible collision with things
already defined.
Actions list
~~~~~~~~~~~
NOTE: Even if some of these actions are labelled as similar to other
keystrokes, remapping the keystrokes will not remap the actions defined here.
[horizontal]
*_bookmark*:: Bookmarks the current room.
Similar to /bookmark.
*_bookmark_local*:: Bookmarks the current room, locally.
Similar to /bookmark_local
*_close_tab*:: Closes the current tab.
This is the same as /close. The first tab (the roster) can not be closed.
*_disconnect*:: Disconnects poezio from the server.
*_quit*:: Exits poezio.
Similar to /quit.
*_reconnect*:: Disconnects then reconnects poezio, if possible.
This is similar to /connect.
*_redraw_screen*:: Redraws the screen.
This isn’t normally useful, similar to Ctrl-l.
*_reload_theme*:: Reloads the theme.
Similar to /theme.
*_remove_bookmark*:: Removes the bookmark on the current room.
Similar to /remove_bookmark.
*_room_left*:: Goes to the room on the left.
Similar to Ctrl-p.
*_room_right*:: Goes to the room on the right.
Similar to Ctrl-n.
*_show_roster*:: Goes to the roster.
Similar to Alt-r.
*_scroll_down*:: Scrolls down in the current buffer.
Similar to PAGEDOWN.
*_scroll_up*:: Scrolls up in the current buffer.
Similar to PAGEUP.
*_scroll_info_down*:: Scrolls down in the info buffer.
Similar to Alt-c.
*_scroll_info_up*:: Scrolls up in the info buffer.
Similar to Alt-d.
*_server_cycle*:: Cycles in the current MUC server.
Similar to /server_cycle in a MUC. If you are not in a MUC, you will get
an error.
*_show_bookmarks*:: Shows the current bookmarks.
Similar to /bookmarks.
*_show_important_room*:: Goes to the most important room.
Similar to Alt-e.
*_show_invitations*:: Shows all the pending MUC invitations.
Similar to /invitations.
*_show_plugins*:: Shows the currently loaded plugins.
Similar to /plugins.
*_show_xmltab*:: Opens an XML tab.
Similar to /xml_tab.
*_toggle_pane*:: Toggles the left pane.
Similar to F4.
Status actions
~~~~~~~~~~~~~~
[horizontal]
*_available*:: Sets the status to _available_.
Similar to /status available.
*_away*:: Sets the status to _away_.
Similar to /status away.
*_chat*:: Sets the status to _chat_.
Similar to /status chat.
*_dnd*:: Sets the status to _dnd_.
Similar to /status dnd.
*_xa*:: Sets the status to _xa_.
Similar to /status xa.
Command execution
~~~~~~~~~~~~~~~~~
With that kind of actions, you can also execute arbitrary commands, with the
__exc__ keyword.
You only have to prefix your command line with *\_exc\_*, and without the _/_.
./kick Partauche added on Ctrl-w
========================
^W = _exc_kick Partauche
========================