From 7bc160c24eb96b57ee78be1c5cbffbf7819ce30e Mon Sep 17 00:00:00 2001 From: James Booth Date: Tue, 2 Aug 2016 23:17:28 +0100 Subject: [PATCH] Update plugin API docs --- .gitignore | 1 + apidocs/c/gen.sh | 2 +- apidocs/c/profapi.h | 41 +++++++++++++++++++++- apidocs/python/conf.py | 2 +- apidocs/python/gen.sh | 2 +- apidocs/python/src/prof.py | 72 ++++++++++++++++++++++++++++++++++++++ 6 files changed, 116 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 8486aba1..cfdbbd7e 100644 --- a/.gitignore +++ b/.gitignore @@ -71,6 +71,7 @@ apidocs/python/src/prof.pyc apidocs/python/plugin.rst apidocs/python/src/plugin.pyc apidocs/c/html/ +apidocs/c/doxygen_sqlite3.db # Temp Vim files **/*.swp diff --git a/apidocs/c/gen.sh b/apidocs/c/gen.sh index e251843b..3ec0582c 100755 --- a/apidocs/c/gen.sh +++ b/apidocs/c/gen.sh @@ -1 +1 @@ -rm -rf html && doxygen c-prof.conf && open html/index.html +rm -rf html && doxygen c-prof.conf diff --git a/apidocs/c/profapi.h b/apidocs/c/profapi.h index 740d257b..c6b293e7 100644 --- a/apidocs/c/profapi.h +++ b/apidocs/c/profapi.h @@ -193,7 +193,7 @@ int prof_win_show(PROF_WIN_TAG win, char *message); /** Show a message in the plugin window, using the specified theme. Themes must be specified in ~/.local/share/profanity/plugin_themes -@param win The {@link PROF_WIN_TAG} of the window to display the message +@param tag The {@link PROF_WIN_TAG} of the window to display the message @param group the group name in the themes file @param key the item name within the group @param def default colour if the theme cannot be found or NULL @@ -247,6 +247,45 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings */ void prof_settings_set_string(char *group, char *key, char *value); +/** +Get a string list setting +Settings must be specified in ~/.local/share/profanity/plugin_settings +The string list setting items are separated by semicolons. +@param group the group name in the settings file +@param key the item name within the group +@return the list setting +*/ +char** prof_settings_get_string_list(char *group, char *key); + +/** +Add an item to a string list setting +Settings must be specified in ~/.local/share/profanity/plugin_settings +If the list does not exist, a new one will be created with the element added +@param group the group name in the settings file +@param key the item name within the group +@param value item to add +*/ +void prof_settings_string_list_add(char *group, char *key, char *value); + +/** +Remove an item from a string list setting +Settings must be specified in ~/.local/share/profanity/plugin_settings +@param group the group name in the settings file +@param key the item name within the group +@param value item to remove +@return 1 if the item was removed, or is not in the list, 0 if the list does not exist +*/ +int prof_settings_string_list_remove(char *group, char *key, char *value); + +/** +Remove all items from a string list setting +Settings must be specified in ~/.local/share/profanity/plugin_settings +@param group the group name in the settings file +@param key the item name within the group +@return 1 if the list was cleared, 0 if the list does not exist +*/ +int prof_settings_string_list_remove_all(char *group, char *key); + /** Get an integer setting Settings must be specified in ~/.local/share/profanity/plugin_settings diff --git a/apidocs/python/conf.py b/apidocs/python/conf.py index 9d2d20a0..bf28caa9 100644 --- a/apidocs/python/conf.py +++ b/apidocs/python/conf.py @@ -110,7 +110,7 @@ todo_include_todos = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'sphinx_rtd_theme' -html_theme = 'classic' +html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/apidocs/python/gen.sh b/apidocs/python/gen.sh index ba9ce4c0..cc0454ef 100755 --- a/apidocs/python/gen.sh +++ b/apidocs/python/gen.sh @@ -1 +1 @@ -sphinx-apidoc -f -o . src && make html && open _build/html/prof.html +sphinx-apidoc -f -o . src && make html diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index e0dbdd0d..d25a5943 100644 --- a/apidocs/python/src/prof.py +++ b/apidocs/python/src/prof.py @@ -460,6 +460,78 @@ def settings_set_string(group, key, value): pass +def settings_get_string_list(group, key): + """Get a string list setting\n + Settings must be specified in ``~/.local/share/profanity/plugin_settings``\n + The string list setting items are separated by semicolons. + + :param group: the group name in the settings file + :param key: the item name within the group + :type group: str or unicode + :type key: str or unicode + :return: the list setting + :rtype: list of str or unicode + + Example: + :: + prof.settings_get_string_list("someplugin", "somelist") + """ + + +def settings_string_list_add(group, key, value): + """Add an item to a string list setting\n + Settings must be specified in ``~/.local/share/profanity/plugin_settings``\n + If the list does not exist, a new one will be created with the element added + + :param group: the group name in the settings file + :param key: the item name within the group + :param value: item to add + :type group: str or unicode + :type key: str or unicode + :type value: str + + Example: + :: + prof.settings_string_list_add("someplugin", "somelist", "anelement") + """ + + +def settings_string_list_remove(group, key, value): + """Remove an item from a string list setting\n + Settings must be specified in ``~/.local/share/profanity/plugin_settings``\n + + :param group: the group name in the settings file + :param key: the item name within the group + :param value: item to remove + :type group: str or unicode + :type key: str or unicode + :type value: str + :return: ``True`` if the item was removed, or is not in the list, ``False`` if the list does not exist + :rtype: boolean + + Example: + :: + prof.settings_string_list_remove("someplugin", "somelist", "anelement") + """ + + +def settings_string_list_remove_all(group, key): + """Remove all items from a string list setting\n + Settings must be specified in ``~/.local/share/profanity/plugin_settings``\n + + :param group: the group name in the settings file + :param key: the item name within the group + :type group: str or unicode + :type key: str or unicode + :return: ``True`` if the list was cleared, ``False`` if the list does not exist + :rtype: boolean + + Example: + :: + prof.settings_string_list_remove_all("someplugin", "somelist") + """ + + def settings_get_int(group, key, default): """Get an integer setting\n Settings must be specified in ``~/.local/share/profanity/plugin_settings``