chore: add docs build to ci (#1582)

* chore: add docs build to ci

* docs: add info to CHANGES

* docs: fix docstring formatting warnings

* docs: fix formatting in administration

* docs: fix formatting in plugin sections

* docs: fix pypi url references

* docs: remove Google+ meta reference

* docs: fix formatting/warnings for plugin dev section

* docs: fix broken links

* docs: use image syntax for screenshots

* fix: add missing doc build deps

Author: sijis

.github/workflows/python-package.yml

@@ -59,3 +59,8 @@ jobs:
       if: ${{ matrix.python-version == '3.9' }}
       run: |
         tox -e security
+
+    - name: Docs
+      if: ${{ matrix.python-version == '3.9' }}
+      run: |
+        tox -e docs

CHANGES.rst

@@ -8,6 +8,7 @@ fixes:
 - chore: bump actions/setup-python version (#1575)
 - backend/telegram: fix missing imports (#1574)
 - chore: ci improvements (#1577, #1583)
+- chore: add docs build to ci (#1582)
 
 
 v6.1.9 (2022-06-11)

docs/README.rst

@@ -32,7 +32,7 @@ Publishing to Read the Docs
 Read the Docs should rebuild the site automatically when new commits are pushed.
 When new project releases are made, it may be necessary to add the new version
 and remove older versions (to prevent clutter in the version drop-down).
-This can be done at https://readthedocs.org/dashboard/errbot/versions/.
+This can be done at https://readthedocs.org/projects/errbot/versions/.
 
 
 .. _Sphinx: http://sphinx-doc.org/

docs/features.rst

@@ -73,8 +73,8 @@ Extensive plugin framework
 .. _VK: https://vk.com/
 .. _Zulip: https://zulipchat.com/
 .. _`logged to Sentry`: https://github.com/errbotio/errbot/wiki/Logging-with-Sentry
-.. _irc: https://pypi.python.org/pypi/irc/
+.. _irc: https://pypi.org/project/irc/
 .. _jabberbot: http://thp.io/2007/python-jabberbot/
 .. _jinja2: http://jinja.pocoo.org/
-.. _six: https://pypi.python.org/pypi/six/
+.. _six: https://pypi.org/project/six/
 .. _slixmpp: https://slixmpp.readthedocs.io/

docs/index.rst

@@ -8,23 +8,19 @@ The goal of the project is to make it easy for you to write your own plugins so
 can make it do whatever you want: a deployment, retrieving some information online,
 trigger a tool via an API, troll a co-worker,...
 
-Errbot is being used in a lot of different contexts: chatops (tools for devops),
-online gaming chatrooms like EVE, video streaming chatrooms like `livecoding.tv <http://livecoding.tv>`_,
-home security, etc.
+Errbot is being used in a lot of different contexts: chatops (tools for devops), chatroom engagement,
+home security, socials platform (such as Slack, Discord, IRC), etc.
 
 Screenshots
 -----------
 
-.. raw:: html
+.. image:: _static/screenshots/thumb_slack.png
+   :target: _static/screenshots/slack.png
+   :alt: Showing output of the built-in help command in Slack
 
-    <div class="screenshots">
-        <a href="_static/screenshots/slack.png" class="fancybox" title="Showing output of the built-in help command in Slack">
-            <img src="_static/screenshots/thumb_slack.png" width="170" height="150" alt="Showing output of the built-in help command in Slack" />
-        </a>
-        <a href="_static/screenshots/telegram.png" class="fancybox" title="Errbot running on Telegram showing the !help command">
-            <img src="_static/screenshots/thumb_telegram.png" width="180" height= "150" alt="Errbot running on Telegram showing the !help command" />
-        </a>
-    </div>
+.. image:: _static/screenshots/thumb_telegram.png
+   :target: _static/screenshots/telegram.png
+   :alt: Errbot running on Telegram showing the !help command
 
 Simple to build upon
 --------------------
@@ -131,7 +127,6 @@ License
 Errbot is free software, available under the GPL-3 license. Please refer to the
 :download:`full license text <gpl-3.0.txt>` for more details.
 
-.. _`Google plus community`: https://plus.google.com/communities/117050256560830486288
 .. _`GitHub page`: http://github.com/errbotio/errbot/
 .. _`plugin list`: https://github.com/errbotio/errbot/wiki
 .. _`open an issue`: https://github.com/errbotio/errbot/issues

docs/requirements.txt

@@ -9,3 +9,4 @@ pyfire
 python-telegram-bot
 slackclient
 hypchat
+pytest

docs/user_guide/administration.rst

@@ -126,52 +126,54 @@ More advanced access controls can be set up using the `ACCESS_CONTROLS` and `ACC
 
 Access controls, allowing commands to be restricted to specific users/rooms.
 Available filters (you can omit a filter or set it to None to disable it):
-  `allowusers`: Allow command from these users only
-  `denyusers`: Deny command from these users
-  `allowrooms`: Allow command only in these rooms (and direct messages)
-  `denyrooms`: Deny command in these rooms
-  `allowargs`: Allow a command's argument from these users only
-  `denyargs`: Deny a command's argument from these users
-  `allowprivate`: Allow command from direct messages to the bot
-  `allowmuc`: Allow command inside rooms
+
+* `allowusers`: Allow command from these users only
+* `denyusers`: Deny command from these users
+* `allowrooms`: Allow command only in these rooms (and direct messages)
+* `denyrooms`: Deny command in these rooms
+* `allowargs`: Allow a command's argument from these users only
+* `denyargs`: Deny a command's argument from these users
+* `allowprivate`: Allow command from direct messages to the bot
+* `allowmuc`: Allow command inside rooms
 
 Rules listed in `ACCESS_CONTROLS_DEFAULT` are applied by default and merged with any commands found in `ACCESS_CONTROLS`.
 
 The options allowusers, denyusers, allowrooms and denyrooms, allowargs, denyargs support unix-style globbing similar to `BOT_ADMINS`.
 
 Command names also support unix-style globs and can optionally be restricted to a specific plugin by prefixing the command with the name of a plugin, separated by a colon. For example, `Health:status` will match the `!status` command of the `Health` plugin and `Health:*` will match all commands defined by the `Health` plugin.
 
-Please note that the first command match found will be used so if you have overlapping patterns you must used an OrderedDict instead of a regular dict: https://docs.python.org/3/library/collections.html#collections.OrderedDict
-
-Example:
-```
-ACCESS_CONTROLS_DEFAULT = {} # Allow everyone access by default
-ACCESS_CONTROLS = {
-    "status": {
-        "allowrooms": ("[email protected]",)
-    },
-    "about": {
-        "denyusers": ("*@evilhost",),
-        "allowrooms": ("[email protected]", "[email protected]")
-    },
-    "uptime": {"allowusers": BOT_ADMINS},
-    "help": {"allowmuc": False},
-    "ChatRoom:*": {"allowusers": BOT_ADMINS},
-}
-```
+.. note::
+    The first command match found will be used so if you have overlapping patterns you must used an OrderedDict instead of a regular dict: https://docs.python.org/3/library/collections.html#collections.OrderedDict
+
+Example::
+
+    ACCESS_CONTROLS_DEFAULT = {} # Allow everyone access by default
+    ACCESS_CONTROLS = {
+        "status": {
+            "allowrooms": ("[email protected]",)
+        },
+        "about": {
+            "denyusers": ("*@evilhost",),
+            "allowrooms": ("[email protected]", "[email protected]")
+        },
+        "uptime": {"allowusers": BOT_ADMINS},
+        "help": {"allowmuc": False},
+        "ChatRoom:*": {"allowusers": BOT_ADMINS},
+    }
 
 The example :download:`config.py <config-template.py>` file contains this information about the format of these options.
 
 If you don't like encoding access controls into the config file, a member of the errbot community has also created a `dynamic ACL module <https://github.com/shengis/err-profiles>`_ which can be administered through chat commands instead.
-Another community solution allows LDAP groups to be checked for membership before allowing the command to be executed.  `LDAP ACL module <https://github.com/marksull/err-ldap>` is practical for managing large groups.  This module functions by decorating bot commands directly in the plugin code, which differs from configuration based ACLs.
+
+Another community solution allows LDAP groups to be checked for membership before allowing the command to be executed.  `LDAP ACL module <https://github.com/marksull/err-ldap>`_ is practical for managing large groups.  This module functions by decorating bot commands directly in the plugin code, which differs from configuration based ACLs.
 
 .. note::
     Different backends have different formats to identify users.
     Refer to the backend-specific notes at the end of the :ref:`configuration <configuration>` chapter to see which format you should use.
 
 
 Command filters
-^^^^^^^^^^^^^^^
+---------------
 
 If our built-in access controls don't fit your needs, you can always create your own easily using *command filters*.
 Command filters are functions which are called automatically by errbot whenever a user executes a command.
@@ -185,7 +187,7 @@ Any method in your plugin which is decorated by :func:`~errbot.cmdfilter` will t
 
 
 Overriding CommandNotFoundFilter
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In some cases, it may be necessary to run other filters before the `CommandNotFoundFilter`.  Since the `CommandNotFoundFilter` is part of the core plugin list loaded by errbot, it can not be directly overridden from another plugin.
 Instead, to prevent `CommandNotFoundFilter` from being called before other filters, exclude the `CommandNotFoundFilter` plugin in the `CORE_PLUGINS` setting in `config.py` and explicitly call the `CommandNotFoundFilter` function from the overriding filter.

docs/user_guide/configuration/discord.rst

@@ -1,14 +1,14 @@
 Discord Backend
 ===============
 
-`Discord <http://discordapp.com>`_ backend for [Errbot](http://errbot.io).  It allows you to use Errbot from Discord to execute commands.
+`Discord <http://discordapp.com>`_ backend for `Errbot <http://errbot.io>`_.  It allows you to use Errbot from Discord to execute commands.
 
-.. Note:
+.. note::
   ⚠️ This backend uses the `discord.py <https://github.com/Rapptz/discord.py>`_ python module which has been discontinued.  Support of this backend will continue on a best effort basis.
 
 Installation
 ------------
-An Errbot instance is required to install the discord back-end.  See the Errbot installation `documentation <http://errbot.io/en/latest/user_guide/setup.html#option-2-installing-errbot-in-a-virtualenv-preferred>`_ for details.
+An Errbot instance is required to install the discord back-end. See the Errbot installation `documentation <http://errbot.io/en/latest/user_guide/setup.html#option-2-installing-errbot-in-a-virtualenv-preferred>`_ for details.
 
 Requirements
 ------------
@@ -17,38 +17,44 @@ Requirements
 
 Virtual Environment
 -------------------
-The steps below are to install the discord back-end in Errbot's virtual environment.  In the examples below, the virtual environment was set to `/opt/errbot/virtualenv` and Errbot initialised in `/opt/errbot`.  The "extra" back-end directory is set to `/opt/errbot/backend`.
+The steps below are to install the discord backend in Errbot's virtual environment.  In the examples below, the virtual environment was set to `/opt/errbot/virtualenv` and Errbot initialised in `/opt/errbot`.  The "extra" back-end directory is set to `/opt/errbot/backend`.
 
 1. If not already set, set Errbot's `BOT_EXTRA_BACKEND_DIR` variable in `/opt/errbot/config.py` to the directory you will use to place additional back-ends.
-.. code: none
+.. code::
+
     BOT_EXTRA_BACKEND_DIR=/opt/errbot/backend
 
 2. Set the back-end to use `Discord`.
-.. code: none
+.. code::
+
     BACKEND = "Discord"
 
 3. Clone repository to your Errbot back-end directory.
-.. code: none
+.. code::
+
     cd /opt/errbot/backend
-    git clone https://github.com/gbin/err-backend-discord.git
+    git clone https://github.com/errbotio/err-backend-discord.git
 
 4. Install back-end dependencies (Errbot's virtual environment must be activated to install the dependencies into it).
-.. code: none
+.. code::
+
     source /opt/errbot/virtualenv/bin/activate
     cd err-backend-discord
     pip install -r requirements.txt
     deactivate
 
-5. Set the bot's token (see _Create a discord application_ for information on how to get the token).
-.. code: none
+5. Set the bot's token (see _Create a discord application for information on how to get the token).
+.. code::
+
     BOT_IDENTITY = {
         "token" : "changeme"
     }
-6. Enable *SERVER MEMBERS INTENT* for your bot on the Discord website.  See `here <https://discordpy.readthedocs.io/en/latest/intents.html?highlight=intents#privileged-intents>_ for the required steps.
+
+6. Enable *SERVER MEMBERS INTENT* for your bot on the Discord website.  See `here <https://discordpy.readthedocs.io/en/latest/intents.html?highlight=intents#privileged-intents>_` for the required steps.
 
 Create a discord application
 ----------------------------
-For further information about getting a bot user into a server please see: https://discordapp.com/developers/docs/topics/oauth2. You can use [this tool](https://discordapi.com/permissions.html) to generate a proper invitation link.
+For further information about getting a bot user into a server please see: https://discordapp.com/developers/docs/topics/oauth2. You can use `this tool <https://discordapi.com/permissions.html>`_ to generate a proper invitation link.
 The reactiflux community have written a quick start guide to `creating a discord bot and getting a token <https://github.com/reactiflux/discord-irc/wiki/Creating-a-discord-bot-&-getting-a-token>`_
 
 Acknowledgements

docs/user_guide/configuration/gitter.rst

@@ -4,7 +4,11 @@ Gitter Backend
 This is a backend for `Gitter <http://gitter.im>`_ for errbot.
 The source code is hosted on `github <https://github.com/errbotio/err-backend-gitter>`_.
 
-`Screenshot <https://raw.githubusercontent.com/errbotio/err-backend-gitter/master/screenshot.png>`_.
+.. image:: https://raw.githubusercontent.com/errbotio/err-backend-gitter/master/screenshot.png
+   :width: 586px
+   :height: 330px
+   :scale: 75%
+   :alt: Gitter backend screenshot
 
 Requirements
 ------------
@@ -17,12 +21,14 @@ Installation
 
 Checkout the backend using git:
 
-.. codeblock:: bash
+.. code::
+
   git checkout https://github.com/errbotio/err-backend-gitter
 
-Edit errbot's configuration file (``config.py``) and set the backend and backend directory variables:
+Edit errbot's configuration file (`config.py`) and set the backend and backend directory variables:
+
+.. code::
 
-.. codeblock:: none
   BACKEND = 'Gitter'
   BOT_EXTRA_BACKEND_DIR = '/path_to/backend'
 
@@ -33,15 +39,16 @@ From there you have can either add an application or use a personal token from a
 Adding an application, workflow for auth
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 1. pip install bottle requests
-2. execute the script: ./oauth.py and it will guide you
+2. execute the script: `./oauth.py`` and it will guide you
 
 Adding as a real user
 ~~~~~~~~~~~~~~~~~~~~~
 1. authenticate as the bot user (new incognito window helps ;) )
 2. go visit https://developer.gitter.im/apps
 3. use directly the token like this in you config.py
 
-.. codeblock:: none
+.. code::
+
   BOT_IDENTITY = {
       'token' : '54537fa855b9a7bbbbbbbbbc568ea7c069d8c34d'
   }

docs/user_guide/configuration/slack.rst

@@ -35,7 +35,7 @@ by setting up `BOT_IDENTITY` as follows::
 Proxy setup
 -------------
 
-In case you need to use a Proxy to connect to Slack, 
+In case you need to use a Proxy to connect to Slack,
 you can set the proxies with the token config.
 
     BOT_IDENTITY = {
@@ -81,10 +81,10 @@ then you can set `CHATROOM_PRESENCE` to a list of channels and groups to join.
 Message size limit
 ------------------
 
-As of the 12th August 2018 the Slack API has a message limit size of 40,000 characters.  Messages 
-larger than 40,000 will be truncated by Slack's API.  Errbot includes the functionality to split 
-messages larger than 40,000 characters into multiple parts.  To reduce the message limit size, set the 
-`MESSAGE_SIZE_LIMIT` variable in the configuration file.  Errbot will use the smallest value between 
+As of the 12th August 2018 the Slack API has a message limit size of 40,000 characters.  Messages
+larger than 40,000 will be truncated by Slack's API.  Errbot includes the functionality to split
+messages larger than 40,000 characters into multiple parts.  To reduce the message limit size, set the
+`MESSAGE_SIZE_LIMIT` variable in the configuration file.  Errbot will use the smallest value between
 the default 40,000 and `MESSAGE_SIZE_LIMIT`.
 
 #MESSAGE_SIZE_LIMIT = 1000