From dc4ac4f37ac6b92014ec41f6233ada96c8484adb Mon Sep 17 00:00:00 2001 From: kaliko Date: Wed, 6 May 2020 18:51:48 +0200 Subject: [PATCH] sphinx: document plugins --- .gitlab-ci.yml | 2 +- doc/source/doc.rst | 4 ++-- doc/source/index.rst | 1 + doc/source/plugins.rst | 27 +++++++++++++++++++++++++++ sid/archive.py | 9 +++++---- sid/bts.py | 12 +++++++++--- sid/echo.py | 12 +++++++----- sid/feeds.py | 16 +++++++++++++--- 8 files changed, 65 insertions(+), 18 deletions(-) create mode 100644 doc/source/plugins.rst diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index fda84b1..024cc8d 100644 --- 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 ad9ffa9..0252040 100644 --- 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 65b0e9b..6d67060 100644 --- 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 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 b8cbfa4..808e364 100644 --- 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[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 1a7fea4..82b31d4 100644 --- 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[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 90ccd90..5bb90c0 100644 --- 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 : append to in queue""" + """ + **commands**: + + * ``!tell queue`` : messages in queue + * ``!tell `` : append to 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 64ddf12..7fba4e2 100644 --- a/sid/feeds.py +++ b/sid/feeds.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- -# Copyright (C) 2011, 2014 kaliko +# Copyright (C) 2011, 2014, 2020 kaliko # 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 -- 2.39.2