docs: Start on a major cleanup of documentation

docs/source/bot.rst

@@ -0,0 +1,17 @@
+.. title:: The bot and its state
+
+.. autoclass:: sopel.bot.Sopel
+    :members:
+
+
+    .. py:attribute:: nick
+
+        Sopel's current nick. Changing this while Sopel is running is unsupported.
+
+    .. py:attribute:: user
+
+        Sopel's user/ident.
+
+    .. py:attribute:: name
+
+        Sopel's "real name", as used for whois.

docs/source/index.rst

@@ -25,152 +25,9 @@ object (``CommandInput`` in *1.x* and *2.x*). By convention, these are named
 ``willie`` and ``trigger`` in *3.x*, and ``bot`` and ``trigger`` from version
 *4.0* onward. For the purposes of this guide, the *4.0* names will be used.
 
-Your modules
-------------
-
-A Sopel module contains one or more ``callable``\s. It may optionally contain
-``configure``, ``setup``, and ``shutdown`` functions. ``callable``\s are given
-a number of attributes, which determine when they will be executed. This is
-done with decorators, imported from :py:mod:`sopel.module`. It may also be
-done by adding the attributes directly, at the same indentation level as the
-function's ``def`` line, following the last line of the function; this is the
-only option in versions prior to *4.0*.
-
-.. py:method:: callable(bot, trigger)
-
-    This is the general function format, called by Sopel when a command is
-    used, a rule is matched, or an event is seen, as determined by the
-    attributes of the function. The details of what this function does are
-    entirely up to the module writer - the only hard requirement from the bot
-    is that it be callable with a ``Sopel`` object and a ``Trigger`` object,
-    as noted above. Usually, methods of the Sopel object will be used in reply
-    to the trigger, but this isn't a requirement.
-
-    The return value of a callable will usually be ``None``. This doesn't need
-    to be explicit; if the function has no ``return`` statement (or simply uses
-    ``return`` with no arguments), ``None`` will be returned. In *3.2+*, the
-    return value can be a constant; in prior versions return values were
-    ignored. Returning a constant instructs the bot to perform some action
-    after the ``callable``'s execution. For example, returning ``NOLIMIT`` will
-    suspend rate limiting on that call. These constants are defined in
-    :py:mod:`sopel.module`, except in version *3.2* in which they are defined
-    as attributes of the ``Sopel`` class.
-
-    Note that the name can, and should, be anything - it doesn't need to be
-    called callable.
-
-    .. py:attribute:: commands
-
-        *See also:* :py:func:`sopel.module.commands`
-
-        A list of commands which will trigger the function. If the Sopel instance
-        is in a channel, or sent a PRIVMSG, where one of these strings is said,
-        preceeded only by the configured prefix (a period, by default), the
-        function will execute.
-
-    .. py:attribute:: rule
-    
-        *See also:* :py:func:`sopel.module.rule`
-
-        A regular expression which will trigger the function. If the Sopel
-        instance is in a channel, or sent a PRIVMSG, where a string matching
-        this expression is said, the function will execute. Note that captured
-        groups here will be retrievable through the ``Trigger`` object later.
-
-        Inside the regular expression, some special directives can be used.
-        ``$nick`` will be replaced with the nick of the bot and ``,`` or ``:``,
-        and ``$nickname`` will be replaced with the nick of the bot.
-
-        Prior to *3.1*, rules could also be made one of three formats of tuple.
-        The values would be joined together to form a singular regular
-        expression.  However, these kinds of rules add no functionality over
-        simple regular expressions, and are considered deprecated in *3.1*.
-
-    .. py:attribute:: event
-    
-        *See also:* :py:func:`sopel.module.event`
-
-        This is one of a number of events, such as ``'JOIN'``, ``'PART'``,
-        ``'QUIT'``, etc. (More details can be found in `RFC 1459`_.) When the
-        Sopel bot is sent one of these events, the function will execute. Note
-        that functions with an event must also be given a ``rule`` to match
-        (though it may be ``'.*'``, which will always match) or they will not
-        be triggered.
-
-        .. _RFC 1459: http://www.irchelp.org/irchelp/rfc/rfc.html
-
-    .. py:attribute:: rate
-    
-        *Availability: 2+*
-
-        *See also:* :py:func:`sopel.module.rate`
-
-        This limits the frequency with which a single user may use the
-        function.  If a function is given a ``rate`` of ``20``, a single user
-        may only use that function once every 20 seconds. This limit applies to
-        each user individually. Users on the ``admin`` list in Sopel's
-        configuration are exempted from rate limits.
-
-    .. py:attribute:: priority
-    
-        *See also:* :py:func:`sopel.module.priority`
-
-        Priority can be one of ``high``, ``medium``, ``low``. It allows you to
-        control the order of callable execution, if your module needs it.
-        Defaults to ``medium``
-
-.. py:method:: setup(sopel)
-
-    This is an optional function of a module, which will be called while the
-    module is being loaded. The purpose of this function is to perform whatever
-    actions are needed to allow a module to function properly (e.g, ensuring
-    that the appropriate configuration variables exist and are set). Note that
-    this normally occurs prior to connection to the server, so the behavior of
-    the Sopel object's messaging functions is undefined.
-
-    Throwing an exception from this function (such as a `ConfigurationError
-    <#sopel.config.ConfigurationError>`_) will prevent any callables in the
-    module from being registered, and provide an error message to the user.
-    This is useful when requiring the presence of configuration values or
-    making other environmental requirements.
-
-    The bot will not continue loading modules or connecting during the
-    execution of this function. As such, an infinite loop (such as an
-    unthreaded polling loop) will cause the bot to hang.
-
-.. py:method:: shutdown(sopel)
-
-    *Availability: 4.1+*
-
-    This is an optional function of a module, which will be called while the
-    Sopel is quitting. Note that this normally occurs after closing connection
-    to the server, so the behavior of the Sopel object's messaging functions
-    is undefined. The purpose of this function is to perform whatever actions
-    are needed to allow a module to properly clean up (e.g, ensuring that any
-    temporary cache files are deleted).
-
-    The bot will not continue notifying other modules or continue quitting
-    during the execution of this function. As such, an infinite loop (such as
-    an unthreaded polling loop) will cause the bot to hang.
-
-.. py:method:: configure(config)
-
-    *Availability: 3+*
-
-    This is an optional function of a module, which will be called during the
-    user's setup of the bot. It's intended purpose is to use the methods of the
-    passed ``Config`` object in order to create the configuration variables it
-    needs to function properly.
-
-    In *3.1+*, the docstring of this function can be used to document the
-    configuration variables that the module uses. This is not currently used
-    by the bot itself; it is merely convention.
-
 The ``Sopel`` class
 --------------------
 
-.. autoclass:: sopel.bot.Sopel
-   :members:
 
 .. py:function:: reply(text,  destination=None, reply_to=None, notice=False)
 

docs/source/newindex.rst

@@ -0,0 +1,29 @@
+.. title:: Sopel IRC Bot
+
+Sopel IRC Bot
+=============
+
+`Sopel <http://sopel.chat>`_ is a Python IRC bot framework. It is designed to
+enable easily writing new utilities and features for your IRC channels.
+
+Quick links
+-----------
+
+* `Latest releases <https://github.com/sopel-irc/sopel/releases>`_
+* `Source code <https://github.com/sopel-irc/sopel>`_
+* `Wiki <https://github.com/sopel-irc/sopel/wiki>`_
+
+..
+    Eventually, add install instructions and Hello world here, and move the
+    tutorial into pages following this one.
+
+Documentation
+-------------
+
+.. toctree::
+    :titlesonly:
+
+    plugin
+    bot
+    trigger
+    api

docs/source/plugin.rst

@@ -0,0 +1,66 @@
+.. title:: Plugin structure
+
+A Sopel plugin consists of a Python module containing one or more
+``callable``\s. It may optionally also contain ``configure``, ``setup``, and
+``shutdown`` hooks.
+
+.. py:method:: callable(bot, trigger)
+
+    A callable is any function which takes as its arguments a `sopel.bot.Sopel`
+    object and a `sopel.trigger.Trigger` object, and is wrapped with
+    appropriate decorators from `sopel.module`. The ``bot`` provides the
+    ability to send messages to the network and check the state of the bot. The
+    ``trigger`` provides information about the line which triggered this
+    function to be called.
+
+    The return value of these function is ignored, unless it is
+    `sopel.module.NOLIMIT`, in which case rate limiting will not be applied for
+    that call.
+
+    Note that the name can, and should, be anything - it doesn't need to be
+    called "callable".
+
+.. py:method:: setup(bot)
+
+    This is an optional function of a plugin, which will be called while the
+    module is being loaded. The purpose of this function is to perform whatever
+    actions are needed to allow a module to function properly (e.g, ensuring
+    that the appropriate configuration variables exist and are set). Note that
+    this normally occurs prior to connection to the server, so the behavior of
+    the messaging functions on the `sopel.bot.Sopel` object it's passed is
+    undefined.
+
+    Throwing an exception from this function (such as a
+    `sopel.config.ConfigurationError`) will prevent any callables in the
+    module from being registered, and provide an error message to the user.
+    This is useful when requiring the presence of configuration values or
+    making other environmental requirements.
+
+    The bot will not continue loading modules or connecting during the
+    execution of this function. As such, an infinite loop (such as an
+    unthreaded polling loop) will cause the bot to hang.
+
+.. py:method:: shutdown(bot)
+
+    This is an optional function of a module, which will be called while the
+    bot is quitting. Note that this normally occurs after closing connection
+    to the server, so the behavior of the messaging functions on the
+    `sopel.bot.Sopel` object it's passed is undefined. The purpose of this
+    function is to perform whatever actions are needed to allow a module to
+    properly clean up (e.g, ensuring that any temporary cache files are
+    deleted).
+
+    The bot will not continue notifying other modules or continue quitting
+    during the execution of this function. As such, an infinite loop (such as
+    an unthreaded polling loop) will cause the bot to hang.
+
+    .. versionadded:: 4.1
+
+.. py:method:: configure(config)
+
+    This is an optional function of a module, which will be called during the
+    user's setup of the bot. It's intended purpose is to use the methods of the
+    passed ``sopel.config.Config`` object in order to create the configuration
+    variables it needs to function properly.
+
+    .. versionadded:: 3.0