sphinx: document plugins

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index fda84b1cd44c6f613013d4ee53d00309f91f758e..024cc8dc4a100fb538ee509d0e8e84ee9499ed9f 100644 (file)
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -37,7 +37,7 @@ tag_release:
 pages:
   stage: build
   script:
-  - pip install sphinx sphinx_rtd_theme slixmpp
+  - pip install sphinx sphinx_rtd_theme slixmpp feedparser python-debianbts
   - sphinx-build -d ./build/doctrees doc/source -b html ./public -D html_theme=sphinx_rtd_theme
   artifacts:
     paths:

diff --git a/doc/source/doc.rst b/doc/source/doc.rst
index ad9ffa96f32591041dd10bbd972c7684de883d0e..0252040e327bde68bcc53c59dbb6b0f64bddf51e 100644 (file)
--- a/doc/source/doc.rst
+++ b/doc/source/doc.rst
@@ -9,8 +9,8 @@ The Bot
     :undoc-members:
     :show-inheritance:
 
-.. user autodecorator:: with sphinx v2.0
-.. autofunction:: sid.sid.botcmd(hidden, name)
+.. need sphinx v2.0 for autodecorator
+.. autodecorator:: sid.sid.botcmd(hidden, name)
 
 Plugin base
 -----------

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 65b0e9be9b083dab09142af2f6d121d14b88cc13..6d670602d4dcfdcde7f50379049a26ddc243a4cf 100644 (file)
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -11,6 +11,7 @@
    :caption: Contents:
 
    doc.rst
+   plugins.rst
    contribute.rst
 
 Indices and tables

diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst
new file mode 100644 (file)
index 0000000..1d74032
--- /dev/null
+++ b/doc/source/plugins.rst
@@ -0,0 +1,27 @@
+Available plugins
+=================
+
+Generic plugins
+---------------
+
+.. automodule:: sid.echo
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sid.feeds.Feeds
+    :members:
+    :show-inheritance:
+
+Debian plugins
+--------------
+
+.. automodule:: sid.archive
+    :members:
+    :show-inheritance:
+
+.. automodule:: sid.bts
+    :members:
+    :show-inheritance:
+
+
+.. vim: spell spelllang=en

diff --git a/sid/archive.py b/sid/archive.py
index b8cbfa408b22fa215f5055baf292d584671fd8e0..808e364a3f1d53b533bf788102bf727f6afc86f6 100644 (file)
--- a/sid/archive.py
+++ b/sid/archive.py
@@ -22,9 +22,11 @@ from .lib import get_pkg
 
 
 class Archive(Plugin):
-    """Fetch package info from the archive
+    """Fetches package info from the archive
     """
+    #: Current stable Suite
     stable_codename = 'buster'
+    #: Pakage name regexp
     re_pkg = re_compile(r'(?P<package>[0-9a-z.+-]+)$')
 
     def __init__(self, bot):
@@ -32,10 +34,9 @@ class Archive(Plugin):
 
     @botcmd
     def archive(self, rcv, args):
-        """Fetch pkg versions info from the archive:
-
-        !archive pkg-name : Returns package versions (by suite)
         """
+        **command** ``!archive pkg-name`` : Returns package versions
+        (by suite)"""
         if not args:
             return
         if len(args) > 1:

diff --git a/sid/bts.py b/sid/bts.py
index 1a7fea46640ceb48340ec85191f6085adad5d7c0..82b31d41ef5398bb8f5ab1478ceed14a115fd6f3 100644 (file)
--- a/sid/bts.py
+++ b/sid/bts.py
@@ -25,6 +25,9 @@ from .plugin import Plugin, botcmd
 
 class Bugs(Plugin):
     """Gets bugs info from the BTS
+
+    .. note::
+      This plugin depends on external module: **python-debianbts**
     """
     re_bugs = re_compile(r'(?<=#)(\d{6,7})')
     re_pkg = re_compile(r'(?P<package>[0-9a-z.+-]+)$')
@@ -35,7 +38,10 @@ class Bugs(Plugin):
                               self.bot.room, self.muc_message)
 
     def muc_message(self, msg):
-        """Handler method dealing with MUC incoming messages"""
+        """Handler method dealing with MUC incoming messages.
+
+        Intercepts bugs number in MUC messages (as #629234), replies a bug
+        summary."""
         # Does not reply to myself
         if msg['mucnick'] == self.bot.nick:
             return
@@ -66,8 +72,8 @@ class Bugs(Plugin):
 
     @botcmd
     def bugs(self, rcv, args):
-        """Intercepts bugs number in messages (as #629234), reply a bug summary.
-        !bugs pkg-name : Returns latest bug reports if any
+        """
+        **command** ``!bugs pkg-name`` : Returns latest bug reports if any
         """
         if not args:
             return

diff --git a/sid/echo.py b/sid/echo.py
index 90ccd900dfc42ff9a2956d21b6220cd547a1a513..5bb90c06768e7e5daaf9e99b6721ef8d3a352784 100644 (file)
--- a/sid/echo.py
+++ b/sid/echo.py
@@ -19,7 +19,7 @@ from .plugin import Plugin, botcmd
 
 
 class Echo(Plugin):
-    """Drop a message to be sent when someone gets online.
+    """Drops a message to be sent when someone gets online.
     """
 
     def __init__(self, bot):
@@ -35,7 +35,7 @@ class Echo(Plugin):
                               self.bot.room, self.log_presence)
 
     def log_presence(self, pres):
-        """Register presence"""
+        """Handler method registering MUC participants presence"""
         self.log.debug('%s: %s', pres['muc']['nick'], pres['type'])
         nick = pres['muc']['nick']
         self.presence.update({nick: (pres['muc']['role'], pres['type'])})
@@ -49,9 +49,11 @@ class Echo(Plugin):
 
     @botcmd
     def tell(self, message, args):
-        """drop a message to be sent when someone gets online.
-        !tell queue        : messages in queue
-        !tell <nick> <msg> : append <msg> to <nick> in queue"""
+        """
+        **commands**:
+
+        * ``!tell queue``        : messages in queue
+        * ``!tell <nick> <msg>`` : append <msg> to <nick> in queue"""
         if not len(args):
             msg = 'Missing arguments:\n{}'.format(self.tell.__doc__)
             self.reply(message, msg)

diff --git a/sid/feeds.py b/sid/feeds.py
index 64ddf1217300b548ded94d947a14cc22aba3b9af..7fba4e25151b390d6c46370b26d28f05efbf8e24 100644 (file)
--- a/sid/feeds.py
+++ b/sid/feeds.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2011, 2014 kaliko <kaliko@azylum.org>
+# Copyright (C) 2011, 2014, 2020 kaliko <kaliko@azylum.org>
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -134,7 +134,14 @@ class FeedMonitor(threading.Thread):
 
 
 class Feeds(Plugin):
+    """
+    .. note::
+      Feeds plugin depends on external module: **feedparser**
+    """
+
+    #: Time between feeds check
     TEMPO = 60
+    #: Default feeds to monitor
     FEEDS = [
         'https://www.debian.org/security/dsa',
         'https://www.debian.org/News/news',
@@ -157,8 +164,11 @@ class Feeds(Plugin):
     @botcmd
     def feeds(self, rcv, args):
         """feeds monitors debian project related feeds.
-        !feeds : registred feeds list
-        !feeds last : last check time"""
+
+        **commands**:
+
+        * ``!feeds`` : registred feeds list
+        * ``!feeds last`` : last check time"""
         if 'last' in args:
             self.reply(rcv, 'Last feeds check: %s' % self.th_mon.last_check)
             return