More docs

build-utils/watch-doc.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+cd `dirname $0`/..
+
+watchmedo shell-command \
+          --patterns="*.py;*.rst" \
+          --recursive \
+          --command='./build-utils/build-doc.sh' \
+          $@

docs/extensions/actions.rst

@@ -0,0 +1,69 @@
+Actions
+=======
+
+
+ExtensionCustomAction
+---------------------
+
+.. autoclass:: ulauncher.api.shared.action.ExtensionCustomAction.ExtensionCustomAction
+
+
+ActionList
+----------
+
+.. autoclass:: ulauncher.api.shared.action.ActionList.ActionList
+
+
+CopyToClipboardAction
+---------------------
+
+.. autoclass:: ulauncher.api.shared.action.CopyToClipboardAction.CopyToClipboardAction
+
+
+DoNothingAction
+---------------
+
+.. autoclass:: ulauncher.api.shared.action.DoNothingAction.DoNothingAction
+
+
+HideWindowAction
+----------------
+
+.. autoclass:: ulauncher.api.shared.action.HideWindowAction.HideWindowAction
+
+
+LaunchAppAction
+---------------
+
+.. autoclass:: ulauncher.api.shared.action.LaunchAppAction.LaunchAppAction
+
+
+OpenAction
+----------
+
+.. autoclass:: ulauncher.api.shared.action.OpenAction.OpenAction
+
+
+OpenUrlAction
+-------------
+
+.. autoclass:: ulauncher.api.shared.action.OpenUrlAction.OpenUrlAction
+
+
+RenderResultListAction
+----------------------
+
+.. autoclass:: ulauncher.api.shared.action.RenderResultListAction.RenderResultListAction
+
+
+RunScriptAction
+---------------
+
+.. autoclass:: ulauncher.api.shared.action.RunScriptAction.RunScriptAction
+
+
+SetUserQueryAction
+------------------
+
+.. autoclass:: ulauncher.api.shared.action.SetUserQueryAction.SetUserQueryAction
+

docs/extensions/debugging.rst

@@ -0,0 +1,58 @@
+Debugging & Logging
+===================
+
+Run Extension Separately
+------------------------
+
+You don't have to restart Ulauncher every time a change is made to your extension.
+For your convenience there is a flag ``--no-extension`` that prevents extensions from starting automatically.
+
+First, start Ulauncher with the following command::
+
+  ulauncher --no-extensions --dev -v
+
+Then find in the logs command to run your extension. It should look like this::
+
+  VERBOSE=1 ULAUNCHER_WS_API=ws://127.0.0.1:5050/ulauncher-demo PYTHONPATH=/home/username/projects/ulauncher /usr/bin/python /home/username/.cache/ulauncher_cache/extensions/ulauncher-demo/main.py
+
+Now when you need to restart your extension hit ``Ctrl+C`` and run the last command again.
+
+
+Debugging With `ipdb <https://github.com/gotcha/ipdb>`_
+-------------------------------------------------------
+
+Here is the easiest way to set a breakpoint and execute code line by line:
+
+1. Install ipdb
+
+  ::
+
+    sudo pip install ipdb
+
+2. In your code add this line wherever you need to break
+
+  ::
+
+    import ipdb; ipdb.set_trace()
+
+3. Restart extension
+
+
+
+Set up Logger
+--------------
+
+Here's all you need to do to enable logging for your extension::
+
+  import logging
+
+  # create an instance of logger at a module level
+  logger = logging.getLogger(__name__)
+
+  # then use these methods in your classes or functions:
+  logger.error('...')
+  logger.warn('...')
+  logger.info('...')
+  logger.debug('...')
+
+

docs/extensions/events.rst

@@ -0,0 +1,42 @@
+Events
+======
+
+
+KeywordQueryEvent
+-----------------
+
+.. autoclass:: ulauncher.api.shared.event.KeywordQueryEvent
+  :members:
+  :undoc-members:
+
+
+ItemEnterEvent
+--------------
+
+.. autoclass:: ulauncher.api.shared.event.ItemEnterEvent
+  :members:
+  :undoc-members:
+
+
+SystemExitEvent
+---------------
+
+.. autoclass:: ulauncher.api.shared.event.SystemExitEvent
+  :members:
+  :undoc-members:
+
+
+PreferencesUpdateEvent
+----------------------
+
+.. autoclass:: ulauncher.api.shared.event.PreferencesUpdateEvent
+  :members:
+  :undoc-members:
+
+
+PreferencesEvent
+----------------
+
+.. autoclass:: ulauncher.api.shared.event.PreferencesEvent
+  :members:
+  :undoc-members:

docs/extensions/examples.rst

@@ -0,0 +1,10 @@
+Examples
+========
+
+Ulauncher Timer
+---------------
+
+Github: https://github.com/Ulauncher/ulauncher-timer
+
+.. figure:: http://i.imgur.com/bc2bzZ8.png
+   :align: center

docs/extensions/intro.rst

@@ -0,0 +1,45 @@
+Overview
+========
+
+
+What is an Extension
+--------------------
+
+Ulauncher extensions are **Python 2** programs that run as separate processes along with the app.
+
+When you run Ulauncher it starts all available extensions so they are ready to react to user events.
+All extensions are terminated when Ulauncher app is closed or crashed.
+
+
+What Extensions Can Do
+----------------------
+
+Extensions have the same capabilities as any other program --
+they can access your directories, make network requests, etc.
+Basically they get the same rights as a user that runs Ulauncher.
+
+Extension API v1 (current) enables extension developers to write **custom handlers for keywords**.
+
+.. figure:: http://i.imgur.com/bc2bzZ8.png
+  :align: center
+
+  "ti" is a keyword, the rest of the query is an argument in this case.
+
+With Extension API it is possible to capture event when user enters "ti<Space>" into the input
+and then render any results bellow the input box.
+
+Extensions can define preferences in ``manifest.json`` that can be overridden by a user
+from Ulauncher Preferences window.
+
+.. NOTE:: Preferences UI is not implemented yet
+
+It is also possible to capture item click (enter) event and run a custom function to respond to that event.
+
+
+Ulauncher ⇄ Extension Communication Layer
+-----------------------------------------
+
+Ulauncher communicates to extensions using WebSockets.
+
+For developer convenience there is an abstraction layer over WebSockets
+that reduces amount of boilerplate code in extensions.

docs/extensions/libs.rst

@@ -0,0 +1,45 @@
+Available Libraries
+===================
+
+Currently it's not possible to define python packages required for your extension.
+However, libraries listed bellow are available to use in extensions since
+they are required for Ulauncher and are pre-installed with the app.
+
+In future we'll make it possible to support ``requirements.txt`` for extensions.
+
+
+`gir1.2-gtk-3.0 <https://lazka.github.io/pgi-docs/>`_
+  GTK+ 3.0
+
+`gir1.2-keybinder-3.0 <https://lazka.github.io/pgi-docs/#Keybinder-3.0>`_
+  Library for registering global key bindings for gtk-based applications in X11.
+
+`gir1.2-webkit2-3.0 <https://lazka.github.io/pgi-docs/#WebKit-3.0>`_
+  JavaScript engine library from WebKitGTK+
+
+`gir1.2-glib-2.0 <https://lazka.github.io/pgi-docs/#GLib-2.0>`_
+  Low level core library
+
+`gir1.2-notify-0.7 <https://lazka.github.io/pgi-docs/#Notify-0.7>`_
+  Desktop notification library (libnotify is a library for sending desktop notifications)
+
+`gir1.2-gdkpixbuf-2.0 <https://lazka.github.io/pgi-docs/#GdkPixbuf-2.0>`_
+  An image loading library
+
+`gir1.2-appindicator3-0.1 <https://lazka.github.io/pgi-docs/#AppIndicator3-0.1>`_
+  Allow applications to export a menu into the panel
+
+`python-dbus <https://github.com/LEW21/pydbus>`_
+  Python DBus library.
+
+`python-pyinotify <https://github.com/seb-m/pyinotify>`_
+  Monitoring filesystems events with inotify on Linux
+
+`python-pysqlite2 <https://docs.python.org/2/library/sqlite3.html>`_
+  DB-API 2.0 interface for SQLite databases
+
+`python-websocket <https://github.com/websocket-client/websocket-client>`_
+  websocket client for python
+
+`python-xdg <http://pyxdg.readthedocs.io/en/latest/index.html>`_
+  Python library supporting various freedesktop standards.