Improve Sphinx docs

5 files changed, 147 insertions, 22 deletions

diff --git a/qutebrowser/api/cmdutils.py b/qutebrowser/api/cmdutils.py
index 093244727..f6a6f6da9 100644
--- a/qutebrowser/api/cmdutils.py
+++ b/qutebrowser/api/cmdutils.py
@@ -17,7 +17,38 @@
 # You should have received a copy of the GNU General Public License
 # along with qutebrowser.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Utilities for command handlers."""
+"""
+qutebrowser has the concept of functions which are exposed to the user as
+commands.
+
+Creating a new command is straightforward::
+
+  from qutebrowser.api import cmdutils
+
+  @cmdutils.register(...)
+  def foo():
+      ...
+
+The commands arguments are automatically deduced by inspecting your function.
+
+The types of the function arguments are inferred based on their default values,
+e.g., an argument `foo=True` will be converted to a flag `-f`/`--foo` in
+qutebrowser's commandline.
+
+The type can be overridden using Python's function annotations::
+
+  @cmdutils.register(...)
+  def foo(bar: int, baz=True):
+      ...
+
+Possible values:
+
+- A callable (``int``, ``float``, etc.): Gets called to validate/convert the value.
+- A python enum type: All members of the enum are possible values.
+- A ``typing.Union`` of multiple types above: Any of these types are valid
+  values, e.g., ``typing.Union[str, int]``.
+"""
+
 
 import inspect
 import typing
@@ -33,15 +64,17 @@ class CommandError(cmdexc.Error):
     """Raised when a command encounters an error while running.
 
     If your command handler encounters an error and cannot continue, raise this
-    exception with an appropriate error message:
+    exception with an appropriate error message::
 
         raise cmdexc.CommandError("Message")
 
     The message will then be shown in the qutebrowser status bar.
 
-    Note that you should only raise this exception while a command handler is
-    run. Raising it at another point causes qutebrowser to crash due to an
-    unhandled exception.
+    .. note::
+
+       You should only raise this exception while a command handler is run.
+       Raising it at another point causes qutebrowser to crash due to an
+       unhandled exception.
     """
 
 
@@ -76,13 +109,7 @@ def check_exclusive(flags: typing.Iterable[bool],
 
 class register:  # noqa: N801,N806 pylint: disable=invalid-name
 
-    """Decorator to register a new command handler.
-
-    Attributes:
-        _instance: The object from the object registry to be used as "self".
-        _name: The name (as string) or names (as list) of the command.
-        _kwargs: The arguments to pass to Command.
-    """
+    """Decorator to register a new command handler."""
 
     def __init__(self, *,
                  instance: str = None,
@@ -95,8 +122,11 @@ class register:  # noqa: N801,N806 pylint: disable=invalid-name
         Args:
             See class attributes.
         """
+        # The object from the object registry to be used as "self".
         self._instance = instance
+        # The name (as string) or names (as list) of the command.
         self._name = name
+        # The arguments to pass to Command.
         self._kwargs = kwargs
 
     def __call__(self, func: typing.Callable) -> typing.Callable:
@@ -127,16 +157,47 @@ class register:  # noqa: N801,N806 pylint: disable=invalid-name
 
 class argument:  # noqa: N801,N806 pylint: disable=invalid-name
 
-    """Decorator to customize an argument for @cmdutils.register.
+    """Decorator to customize an argument.
+
+    You can customize how an argument is handled using the ``@cmdutils.argument``
+    decorator *after* ``@cmdutils.register``. This can, for example, be used to
+    customize the flag an argument should get::
+
+      @cmdutils.register(...)
+      @cmdutils.argument('bar', flag='c')
+      def foo(bar):
+          ...
+
+    For a ``str`` argument, you can restrict the allowed strings using ``choices``::
+
+      @cmdutils.register(...)
+      @cmdutils.argument('bar', choices=['val1', 'val2'])
+      def foo(bar: str):
+          ...
+
+    For ``typing.Union`` types, the given ``choices`` are only checked if other types
+    (like ``int``) don't match.
 
-    Attributes:
-        _argname: The name of the argument to handle.
-        _kwargs: Keyword arguments, valid ArgInfo members
+    The following arguments are supported for ``@cmdutils.argument``:
+
+    - ``flag``: Customize the short flag (``-x``) the argument will get.
+    - ``value``: Tell qutebrowser to fill the argument with special values:
+
+      * ``value=cmdutils.Value.count``: The ``count`` given by the user to the command.
+      * ``value=cmdutils.Value.win_id``: The window ID of the current window.
+      * ``value=cmdutils.Value.cur_tab``: The tab object which is currently focused.
+
+    - ``completion``: A completion function to use when completing arguments for
+      the given command.
+    - ``choices``: The allowed string choices for the argument.
+
+    The name of an argument will always be the parameter name, with any trailing
+    underscores stripped and underscores replaced by dashes.
     """
 
     def __init__(self, argname: str, **kwargs: typing.Any) -> None:
-        self._argname = argname
-        self._kwargs = kwargs
+        self._argname = argname   # The name of the argument to handle.
+        self._kwargs = kwargs  # Valid ArgInfo members.
 
     def __call__(self, func: typing.Callable) -> typing.Callable:
         funcname = func.__name__
diff --git a/qutebrowser/api/config.py b/qutebrowser/api/config.py
index 4a5d73936..0c633e54d 100644
--- a/qutebrowser/api/config.py
+++ b/qutebrowser/api/config.py
@@ -25,6 +25,16 @@ from PyQt5.QtCore import QUrl
 
 from qutebrowser.config import config
 
+#: Simplified access to config values using attribute acccess.
+#: For example, to access the ``content.javascript.enabled`` setting,
+#: you can do::
+#:
+#:   if config.val.content.javascript.enabled:
+#:       ...
+#:
+#: This also supports setting configuration values::
+#:
+#:   config.val.content.javascript.enabled = False
 val = typing.cast('config.ConfigContainer', None)
 
 
diff --git a/qutebrowser/api/downloads.py b/qutebrowser/api/downloads.py
index 82c68d0bd..a2a37d931 100644
--- a/qutebrowser/api/downloads.py
+++ b/qutebrowser/api/downloads.py
@@ -52,6 +52,21 @@ def download_temp(url: QUrl) -> TempDownload:
     """Download the given URL into a file object.
 
     The download is not saved to disk.
+
+    Returns a ``TempDownload`` object, which triggers a ``finished`` signal
+    when the download has finished::
+
+        dl = downloads.download_temp(QUrl("https://www.example.com/"))
+        dl.finished.connect(functools.partial(on_download_finished, dl))
+
+    After the download has finished, its ``successful`` attribute can be
+    checked to make sure it finished successfully. If so, its contents can be
+    read by accessing the ``fileobj`` attribute::
+
+        def on_download_finished(download: downloads.TempDownload) -> None:
+            if download.successful:
+                print(download.fileobj.read())
+                download.fileobj.close()
     """
     fobj = io.BytesIO()
     fobj.name = 'temporary: ' + url.host()
diff --git a/qutebrowser/api/hook.py b/qutebrowser/api/hook.py
index 3f06121da..84e103cbd 100644
--- a/qutebrowser/api/hook.py
+++ b/qutebrowser/api/hook.py
@@ -36,7 +36,17 @@ def _add_module_info(func: typing.Callable) -> loader.ModuleInfo:
 
 class init:
 
-    """Decorator to mark a function to run when initializing."""
+    """Decorator to mark a function to run when initializing.
+
+    The decorated function gets called with a
+    :class:`qutebrowser.api.apitypes.InitContext` as argument.
+
+    Example::
+
+        @hook.init()
+        def init(_context):
+            message.info("Extension initialized.")
+    """
 
     def __call__(self, func: typing.Callable) -> typing.Callable:
         info = _add_module_info(func)
@@ -48,7 +58,30 @@ class init:
 
 class config_changed:
 
-    """Decorator to get notified about changed configs."""
+    """Decorator to get notified about changed configs.
+
+    By default, the decorated function is called when any change in the config
+    occurs::
+
+        @hook.config_changed()
+        def on_config_changed():
+            ...
+
+    When an option name is passed, it's only called when the given option was
+    changed::
+
+        @hook.config_changed('content.javascript.enabled')
+        def on_config_changed():
+            ...
+
+    Alternatively, a part of an option name can be specified. In the following
+    snippet, ``on_config_changed`` gets called when either
+    ``bindings.commands`` or ``bindings.key_mappings`` have changed::
+
+        @hook.config_changed('bindings')
+        def on_config_changed():
+            ...
+    """
 
     def __init__(self, option_filter: str = None) -> None:
         self._filter = option_filter
diff --git a/qutebrowser/api/interceptor.py b/qutebrowser/api/interceptor.py
index a40635fca..634ae1409 100644
--- a/qutebrowser/api/interceptor.py
+++ b/qutebrowser/api/interceptor.py
@@ -27,7 +27,13 @@ from qutebrowser.extensions.interceptors import Request
 def register(interceptor: interceptors.InterceptorType) -> None:
     """Register a request interceptor.
 
-    Whenever a request happens, the interceptor gets called with a Request
-    object.
+    Whenever a request happens, the interceptor gets called with a
+    :class:`Request` object.
+
+    Example::
+
+        def intercept(request: interceptor.Request) -> None:
+            if request.request_url.host() == 'badhost.example.com':
+                request.block()
     """
     interceptors.register(interceptor)