From 5ca119827b72beba3a2cc247bedf50103d900436 Mon Sep 17 00:00:00 2001 From: Damien Churchill Date: Wed, 22 Jul 2009 23:53:30 +0000 Subject: [PATCH] update documentation about the webui --- deluge/ui/web/auth.py | 21 +++++--- deluge/ui/web/common.py | 3 ++ deluge/ui/web/gen_gettext.py | 3 ++ deluge/ui/web/json_api.py | 72 ++++++++++++++++--------- deluge/ui/web/pluginmanager.py | 7 ++- docs/source/index.rst | 6 ++- docs/source/modules/ui/web/auth.rst | 5 ++ docs/source/modules/ui/web/common.rst | 5 ++ docs/source/modules/ui/web/json_api.rst | 5 ++ 9 files changed, 94 insertions(+), 33 deletions(-) create mode 100644 docs/source/modules/ui/web/auth.rst create mode 100644 docs/source/modules/ui/web/common.rst create mode 100644 docs/source/modules/ui/web/json_api.rst diff --git a/deluge/ui/web/auth.py b/deluge/ui/web/auth.py index 6720ed7f4..6422625c5 100644 --- a/deluge/ui/web/auth.py +++ b/deluge/ui/web/auth.py @@ -53,6 +53,9 @@ from deluge.ui.web.json_api import JSONComponent, export log = logging.getLogger(__name__) class Auth(JSONComponent): + """ + The component that implements authentification into the JSON interface. + """ def __init__(self): super(Auth, self).__init__("Auth") @@ -61,8 +64,9 @@ class Auth(JSONComponent): """ Creates a new session. - :keyword login: str, the username of the user logging in, currently + :keyword login: the username of the user logging in, currently \ only for future use. + :type login: string """ m = hashlib.md5() m.update(login) @@ -87,7 +91,8 @@ class Auth(JSONComponent): """ Change the password. - :param new_password: str, the password to change to + :param new_password: the password to change to + :type new_password: string """ log.debug("Changing password") d = Deferred() @@ -106,9 +111,10 @@ class Auth(JSONComponent): """ Check a session to see if it's still valid. - :param session_id: str, the id for the session to remove + :param session_id: the id for the session to remove + :type session_id: string :returns: True if the session is valid, False if not. - :rtype: bool + :rtype: booleon """ d = Deferred() config = component.get("DelugeWeb").config @@ -120,7 +126,8 @@ class Auth(JSONComponent): """ Removes a session. - :param session_id: str, the id for the session to remove + :param session_id: the id for the session to remove + :type session_id: string """ d = Deferred() config = component.get("DelugeWeb").config @@ -133,8 +140,10 @@ class Auth(JSONComponent): """ Test a password to see if it's valid. - :param password: str, the password to test + :param password: the password to test + :type password: string :returns: a session id or False + :rtype: string or False """ config = component.get("DelugeWeb").config d = Deferred() diff --git a/deluge/ui/web/common.py b/deluge/ui/web/common.py index 4ebf198c6..a47261f5d 100644 --- a/deluge/ui/web/common.py +++ b/deluge/ui/web/common.py @@ -40,6 +40,9 @@ from deluge import common _ = lambda x: gettext.gettext(x).decode("utf-8") class Template(MakoTemplate): + """ + A template that adds some built-ins to the rendering + """ builtins = { "_": _, diff --git a/deluge/ui/web/gen_gettext.py b/deluge/ui/web/gen_gettext.py index 0aa340823..3c6c1076f 100644 --- a/deluge/ui/web/gen_gettext.py +++ b/deluge/ui/web/gen_gettext.py @@ -1,4 +1,7 @@ #!/usr/bin/python +""" +Script to go through the javascript files and dynamically generate gettext.js +""" import os import re diff --git a/deluge/ui/web/json_api.py b/deluge/ui/web/json_api.py index 4117bd73a..7b28fb180 100644 --- a/deluge/ui/web/json_api.py +++ b/deluge/ui/web/json_api.py @@ -68,8 +68,10 @@ def export(auth_level=AUTH_LEVEL_DEFAULT): Decorator function to register an object's method as an RPC. The object will need to be registered with an `:class:RPCServer` to be effective. - :param func: function, the function to export - :param auth_level: int, the auth level required to call this method + :param func: the function to export + :type func: function + :keyword auth_level: the auth level required to call this method + :type auth_level: int """ global AUTH_LEVEL_DEFAULT @@ -254,8 +256,10 @@ class JSON(resource.Resource, component.Component): Registers an object to export it's rpc methods. These methods should be exported with the export decorator prior to registering the object. - :param obj: object, the object that we want to export - :param name: str, the name to use, if None, it will be the class name of the object + :param obj: the object that we want to export + :type obj: object + :param name: the name to use, if None, it will be the class name of the object + :type name: string """ name = name or obj.__class__.__name__ name = name.lower() @@ -289,6 +293,11 @@ HOSTS_INFO = 4 FILES_KEYS = ["files", "file_progress", "file_priorities"] class WebApi(JSONComponent): + """ + The component that implements all the methods required for managing + the web interface. + """ + def __init__(self): super(WebApi, self).__init__("Web") self.host_list = ConfigManager("hostlist.conf.1.2", DEFAULT_HOSTS) @@ -297,7 +306,8 @@ class WebApi(JSONComponent): """ Return the information about a host - :param host_id: str, the id of the host + :param host_id: the id of the host + :type host_id: string :returns: the host information :rtype: list """ @@ -310,7 +320,8 @@ class WebApi(JSONComponent): """ Connect the client to a daemon - :param host_id: str, the id of the daemon in the host list + :param host_id: the id of the daemon in the host list + :type host_id: string :returns: the methods the daemon supports :rtype: list """ @@ -329,7 +340,7 @@ class WebApi(JSONComponent): The current connection state. :returns: True if the client is connected - :rtype: bool + :rtype: booleon """ d = Deferred() d.callback(client.connected()) @@ -350,10 +361,12 @@ class WebApi(JSONComponent): """ Gather the information required for updating the web interface. - :param keys: list, the information about the torrents to gather - :param filter_dict: dict, the filters to apply when selecting torrents. + :param keys: the information about the torrents to gather + :type keys: list + :param filter_dict: the filters to apply when selecting torrents. + :type filter_dict: dictionary :returns: The torrent and ui information. - :rtype: dict + :rtype: dictionary """ ui_info = { "torrents": None, @@ -421,9 +434,10 @@ class WebApi(JSONComponent): """ Gets the files for a torrent in tree format - :param torrent_id: string, the id of the torrent to retrieve. + :param torrent_id: the id of the torrent to retrieve. + :type torrent_id: string :returns: The torrents files in a tree - :rtype: dict + :rtype: dictionary """ main_deferred = Deferred() d = client.core.get_torrent_status(torrent_id, FILES_KEYS) @@ -435,9 +449,10 @@ class WebApi(JSONComponent): """ Download a torrent file from a url to a temporary directory. - :param url: str, the url of the torrent + :param url: the url of the torrent + :type url: string :returns: the temporary file name of the torrent file - :rtype: str + :rtype: string """ tmp_file = os.path.join(tempfile.gettempdir(), url.split("/")[-1]) @@ -452,7 +467,8 @@ class WebApi(JSONComponent): """ Return information about a torrent on the filesystem. - :param filename: str, the path to the torrent + :param filename: the path to the torrent + :type filename: string :returns: { "filename": the torrent file @@ -461,6 +477,7 @@ class WebApi(JSONComponent): "files": the files the torrent contains "info_hash" the torrents info_hash } + :rtype: dictionary """ d = Deferred() try: @@ -509,6 +526,9 @@ class WebApi(JSONComponent): def get_host_status(self, host_id): """ Returns the current status for the specified host. + + :param host_id: the hash id of the host + :type host_id: string """ main_deferred = Deferred() @@ -551,12 +571,12 @@ class WebApi(JSONComponent): return main_deferred @export - def stop_daemon(self, connection_id): + def stop_daemon(self, host_id): """ Stops a running daemon. - :param connection_id: str, the hash id of the connection - + :param host_id: the hash id of the host + :type host_id: string """ main_deferred = Deferred() host = self.get_host(connection_id) @@ -589,10 +609,14 @@ class WebApi(JSONComponent): """ Adds a host to the list. - :param host: str, the hostname - :param port: int, the port - :param username: str, the username to login as - :param password: str, the password to login with + :param host: the hostname + :type host: string + :param port: the port + :type port: int + :keyword username: the username to login as + :type username: string + :keyword password: the password to login with + :type password: string """ d = Deferred() @@ -621,8 +645,8 @@ class WebApi(JSONComponent): """ Removes a host for the list - :param connection_Id: str, the hash id of the connection - + :param host_id: the hash id of the host + :type host_id: string """ d = Deferred() host = self.get_host(connection_id) diff --git a/deluge/ui/web/pluginmanager.py b/deluge/ui/web/pluginmanager.py index 885c9ae9c..c05fb1337 100644 --- a/deluge/ui/web/pluginmanager.py +++ b/deluge/ui/web/pluginmanager.py @@ -49,13 +49,18 @@ class PluginManager(PluginManagerBase, Component): PluginManagerBase.__init__(self, "web.conf", "deluge.plugin.web") def start(self): - """Start up the plugin manager""" + """ + Start up the plugin manager + """ # Update the enabled plugins from the core d = client.core.get_enabled_plugins() d.addCallback(self._on_get_enabled_plugins) def stop(self): + """ + Stop the plugin manager + """ self.disable_plugins() def update(self): diff --git a/docs/source/index.rst b/docs/source/index.rst index 2feba1fed..f7c20392a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -25,6 +25,8 @@ Modules .. toctree:: :maxdepth: 2 + :glob: - modules/common - modules/config + modules/* + modules/*/* + modules/*/*/* \ No newline at end of file diff --git a/docs/source/modules/ui/web/auth.rst b/docs/source/modules/ui/web/auth.rst new file mode 100644 index 000000000..a2becfd08 --- /dev/null +++ b/docs/source/modules/ui/web/auth.rst @@ -0,0 +1,5 @@ +:mod:`deluge.ui.web.auth` +========================= + +.. automodule:: deluge.ui.web.auth + :members: diff --git a/docs/source/modules/ui/web/common.rst b/docs/source/modules/ui/web/common.rst new file mode 100644 index 000000000..0be05bec9 --- /dev/null +++ b/docs/source/modules/ui/web/common.rst @@ -0,0 +1,5 @@ +:mod:`deluge.ui.web.common` +=========================== + +.. automodule:: deluge.ui.web.common + :members: diff --git a/docs/source/modules/ui/web/json_api.rst b/docs/source/modules/ui/web/json_api.rst new file mode 100644 index 000000000..f82808941 --- /dev/null +++ b/docs/source/modules/ui/web/json_api.rst @@ -0,0 +1,5 @@ +:mod:`deluge.ui.web.json_api` +============================= + +.. automodule:: deluge.ui.web.json_api + :members: