doc: Improve and update

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 3f24004956b81be0b719a22786d313a819455c5c..51bf4f429ba0546e5ac091a64cdfdb86ee12ed4f 100644 (file)
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -87,7 +87,8 @@ pygments_style = 'sphinx'
 #        }
 html_theme = 'alabaster'
 html_theme_options = {
-         'donate_url': 'https://liberapay.com/kaliko/'
+         'donate_url': 'https://liberapay.com/kaliko/',
+         'style_external_links': True,
          }
 html_show_sphinx = False
 

diff --git a/doc/source/doc.rst b/doc/source/doc.rst
index 10bc5e8648bee68d512ef8a71dca5dfb78750116..aeb9f02f7bca15825f020a4677288556f20fa472 100644 (file)
--- a/doc/source/doc.rst
+++ b/doc/source/doc.rst
@@ -22,3 +22,39 @@ The plugin class to derive from.
     :undoc-members:
 
 .. vim: spell spelllang=en
+
+
+Available plugins
+-----------------
+
+Generic plugins
+~~~~~~~~~~~~~~~
+
+.. automodule:: sid.echo
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sid.feeds.Feeds
+    :members:
+    :show-inheritance:
+
+.. automodule:: sid.log
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sid.rtbl.RTBL
+    :members:
+    :show-inheritance:
+
+Debian plugins
+~~~~~~~~~~~~~~
+
+.. automodule:: sid.archive
+    :members:
+    :show-inheritance:
+
+.. automodule:: sid.bts
+    :members:
+    :show-inheritance:
+
+.. vim: spell spelllang=en

diff --git a/doc/source/index.rst b/doc/source/index.rst
index f25adc503d5c0f6c3eed84d5fc1cbabc9eb50b79..4dbe819b609a59bf70f401da02358525046bcd7c 100644 (file)
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -2,6 +2,7 @@
    sphinx-quickstart on Tue May  5 12:46:38 2020.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
+.. _home:
 
 .. include:: ../../README.rst
 
@@ -10,9 +11,10 @@
    :maxdepth: 2
    :caption: Contents:
 
+   self
    rtbl.rst
-   doc.rst
    plugins.rst
+   doc.rst
    contribute.rst
 
 Indices and tables

diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst
index e7c4fdb86c4d1ea3b27b971087d5e35dbab9db44..bb60e0eb0cef1ae1576e8d976876a1f7c78f5e99 100644 (file)
--- a/doc/source/plugins.rst
+++ b/doc/source/plugins.rst
@@ -1,35 +1,28 @@
-Available plugins
-=================
-
 Generic plugins
----------------
+===============
 
-.. automodule:: sid.echo
-    :members:
-    :show-inheritance:
+This page documents plugin import usage only.
 
-.. autoclass:: sid.feeds.Feeds
-    :members:
-    :show-inheritance:
+Real time block list
+--------------------
+.. automodule:: sid.rtbl
+   :noindex:
 
-.. automodule:: sid.log
-    :members:
-    :show-inheritance:
+Feeds
+-----
+.. automodule:: sid.feeds
+   :noindex:
 
-.. autoclass:: sid.rtbl.RTBL
-    :members:
-    :show-inheritance:
 
 Debian plugins
---------------
+==============
 
+Archive
+-------
 .. automodule:: sid.archive
-    :members:
-    :show-inheritance:
+   :noindex:
 
+Bugs
+----
 .. automodule:: sid.bts
-    :members:
-    :show-inheritance:
-
-
-.. vim: spell spelllang=en
+   :noindex:

diff --git a/sid/archive.py b/sid/archive.py
index 6875f1bad430717e1adbadc23630e12eb90bfaf7..e399a59430ae50dd54ee6055c711640fa014f955 100644 (file)
--- a/sid/archive.py
+++ b/sid/archive.py
@@ -1,6 +1,10 @@
 # -*- coding: utf-8 -*-
 # SPDX-FileCopyrightText: 2020 kaliko <kaliko@azylum.org>
 # SPDX-License-Identifier: GPL-3.0-or-later
+"""Fetch packages info from the archive
+
+>>> from sid.archive import Archive
+"""
 
 from re import compile as re_compile
 

diff --git a/sid/bts.py b/sid/bts.py
index 305ef717b50318c750f8a0a1e26bdd18ca77e1df..fa882444aa4c32e0bc25fdf1e0969892d05fe0c6 100644 (file)
--- a/sid/bts.py
+++ b/sid/bts.py
@@ -2,6 +2,10 @@
 # SPDX-FileCopyrightText: 2015, 2021 kaliko <kaliko@azylum.org>
 # SPDX-FileCopyrightText: 2010, 2011 Anaël Verrier <elghinn@free.fr>
 # SPDX-License-Identifier: GPL-3.0-or-later
+"""Intercepts bugs numbers in MUC messages and send info about it
+
+>>> from sid.bts import Bugs
+"""
 
 from re import compile as re_compile
 

diff --git a/sid/feeds.py b/sid/feeds.py
index 466aaece82ee6f0554bd81fb3883b946f1796fd2..3fe7ce9ecdd406dbe9d9ba43b977e01c5e6144ba 100644 (file)
--- a/sid/feeds.py
+++ b/sid/feeds.py
@@ -1,6 +1,21 @@
 # -*- coding: utf-8 -*-
 # SPDX-FileCopyrightText: 2011, 2014, 2020 kaliko <kaliko@azylum.org>
 # SPDX-License-Identifier: GPL-3.0-or-later
+"""Publish news from various Debian feeds (security, planet, package tracker, see :py:obj:`sid.feeds.Feeds.FEEDS` for defaults).
+
+Can easily be used for other feeds (rss, atom).
+
+.. note::
+  Feeds plugin depends on external module: **feedparser**
+
+>>> from sid.feeds import Feeds
+>>> # Time between check in seconds
+>>> Feeds.TEMPO = 60
+>>> # Fedds to monitor, cf. sid.feeds.Feeds.FEEDS for defaults
+>>> Feeds.FEEDS = [
+        'https://example.org/feeds/atom/news.atom.xml'
+        ]
+"""
 
 import datetime
 import threading

diff --git a/sid/rtbl.py b/sid/rtbl.py
index 424a17982f0ea8e665969dd8c9e6560eb5e61bc9..1539b28a1273be86420c38b9df6d99c4dfc0f8c9 100644 (file)
--- a/sid/rtbl.py
+++ b/sid/rtbl.py
@@ -1,7 +1,17 @@
 # -*- coding: utf-8 -*-
 # SPDX-FileCopyrightText: 2023 kaliko <kaliko@azylum.org>
 # SPDX-License-Identifier: GPL-3.0-or-later
-"""A Real Time Block List plugin"""
+"""A Real Time Block List plugin, cf https://xmppbl.org.
+
+>>> from sid.rtbl import RTBL, BL
+>>> RTBL.pubsub_server = 'xmppbl.org'
+>>> # Optional: Node to subcribe, defaults to 'muc_bans_sha256'
+>>> RTBL.node = 'muc_bans_sha256'
+>>> # Optional: Add this JID hash to the list, default is empty, usefull for test
+>>> BL.init = {'1312b8ca593cd074f39ef15cc8442cdf426b21480958836d9ab678ca45ed1312': 'Test!'}
+>>> # Optional: Set plugin log level, default inherit from the bot
+>>> RTBL.log_level = logging.DEBUG
+"""
 
 from hashlib import sha256
 from typing import Dict, Optional