From 4ae9245246f33ffd5bb5e4d63f21947e5cf10ec3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nguy=E1=BB=85n=20Gia=20Phong?= <mcsinyx@disroot.org>
Date: Mon, 21 Sep 2020 17:05:20 +0700
Subject: [PATCH] Update changelog and docs for vicious.call

---
 CHANGELOG.rst                 | 12 +++++++--
 docs/requirements.txt         |  1 +
 docs/source/conf.py           |  5 +---
 docs/source/usage-awesome.rst | 47 +++++++++++++++++++++++++----------
 4 files changed, 46 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index c06c51d..af8c84d 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -1,8 +1,16 @@
 Changelog
 =========
 
-Changes in 2.5.0 (WIP)
-----------------------
+Changes in 2.5.0
+----------------
+
+Fixed:
+
+- ``vicious.call`` freezing awesome when used with asynchronous widget types
+
+Added:
+
+- ``vicious.call_async`` asynchronous analogous to ``vicious.call``
 
 Moved:
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
index eb96319..2e75f9a 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1,3 @@
 Sphinx >= 3
+sphinx_rtd_theme
 sphinxcontrib-luadomain
diff --git a/docs/source/conf.py b/docs/source/conf.py
index a9dd63c..33edd5f 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -28,10 +28,7 @@ templates_path = ['_templates']
 exclude_patterns = []
 
 # Options for HTML output
-html_theme = 'alabaster'
-html_theme_options = {
-    'github_user': 'vicious-widgets', 'github_repo': 'vicious',
-    'github_button': True, 'github_count': False}
+html_theme = 'sphinx_rtd_theme'
 html_show_copyright = False
 
 # Add any paths that contain custom static files (such as style sheets)
diff --git a/docs/source/usage-awesome.rst b/docs/source/usage-awesome.rst
index 5d97921..20b2888 100644
--- a/docs/source/usage-awesome.rst
+++ b/docs/source/usage-awesome.rst
@@ -31,8 +31,7 @@ call ``vicious.register`` to register it with Vicious:
    :param widget: awesome widget created from
                   ``awful.widget`` or ``wibox.widget``
 
-   :param wtype:
-      either of
+   :param wtype: either of
 
       * Vicious widget type: any widget type
         :ref:`provided by Vicious <widgets>` or customly defined.
@@ -40,8 +39,7 @@ call ``vicious.register`` to register it with Vicious:
         awesome configuration can be registered as widget types
         (see :ref:`custom-wtype`).
 
-   :param format:
-      either of
+   :param format: either of
 
       * string: ``$key`` will be replaced by respective value in the table
         ``t`` returned by the widget type, i.e. use ``$1``, ``$2``, etc.
@@ -105,25 +103,23 @@ vicious.force
 
    :param wtable: table of one or more widgets to be updated
 
-vicious.call
-------------
+vicious.call[_async]
+--------------------
 
 .. lua:function:: vicious.call(wtype, format, warg)
 
-   Fetch data from the widget type to use it outside of the widget
+   Get formatted data from a synchronous widget type
    (:ref:`example <call-example>`).
 
-   :param wtype:
-      either of
+   :param wtype: either of
 
-      * Vicious widget type: any widget type
+      * Vicious widget type: any synchronous widget type
         :ref:`provided by Vicious <widgets>` or customly defined.
       * ``function``: custom function from your own
         awesome configuration can be registered as widget types
         (see :ref:`custom-wtype`).
 
-   :param format:
-      either of
+   :param format: either of
 
       * string: ``$key`` will be replaced by respective value in the table
         ``t`` returned by the widget type, i.e. use ``$1``, ``$2``, etc.
@@ -132,7 +128,32 @@ vicious.call
       * ``function (widget, args)`` can be used to manipulate data returned
         by the widget type (see :ref:`format-func`).
 
-   :param warg: arguments to be passed to widget types, e.g. the battery ID.
+   :param warg: arguments to be passed to the widget type, e.g. the battery ID.
+
+   :return: ``nil`` if the widget type is asynchronous,
+            otherwise the formatted data from with widget type.
+
+.. lua:function:: vicious.call_async(wtype, format, warg, callback)
+
+   Get formatted data from an asynchronous widget type.
+
+   :param wtype: any asynchronous widget type
+                 :ref:`provided by Vicious <widgets>` or customly defined.
+
+   :param format: either of
+
+      * string: ``$key`` will be replaced by respective value in the table
+        ``t`` returned by the widget type, i.e. use ``$1``, ``$2``, etc.
+        to retrieve data from an integer-indexed table (a.k.a. array);
+        ``${foo bar}`` will be substituted by ``t["{foo bar}"]``.
+      * ``function (widget, args)`` can be used to manipulate data returned
+        by the widget type (see :ref:`format-func`).
+
+   :param warg: arguments to be passed to the widget type.
+
+   :param callback: function taking the formatted data from with widget type.
+                    If the given widget type happens to be synchronous,
+                    ``nil`` will be passed to ``callback``.
 
 .. _awesome: https://awesomewm.org/
 .. _awful.widget.watch: