From: kaliko Date: Sat, 25 Mar 2023 14:15:13 +0000 (+0100) Subject: doc: Improve and update X-Git-Tag: 0.4.0~2 X-Git-Url: https://git.kaliko.me/?p=sid.git;a=commitdiff_plain;h=b32d7a8cb7b1bd5cd16e461d14ed94891b93014f doc: Improve and update --- diff --git a/doc/source/conf.py b/doc/source/conf.py index 3f24004..51bf4f4 100644 --- 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 10bc5e8..aeb9f02 100644 --- 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 f25adc5..4dbe819 100644 --- 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 e7c4fdb..bb60e0e 100644 --- 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 6875f1b..e399a59 100644 --- a/sid/archive.py +++ b/sid/archive.py @@ -1,6 +1,10 @@ # -*- coding: utf-8 -*- # SPDX-FileCopyrightText: 2020 kaliko # 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 305ef71..fa88244 100644 --- a/sid/bts.py +++ b/sid/bts.py @@ -2,6 +2,10 @@ # SPDX-FileCopyrightText: 2015, 2021 kaliko # SPDX-FileCopyrightText: 2010, 2011 Anaël Verrier # 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 466aaec..3fe7ce9 100644 --- a/sid/feeds.py +++ b/sid/feeds.py @@ -1,6 +1,21 @@ # -*- coding: utf-8 -*- # SPDX-FileCopyrightText: 2011, 2014, 2020 kaliko # 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 424a179..1539b28 100644 --- a/sid/rtbl.py +++ b/sid/rtbl.py @@ -1,7 +1,17 @@ # -*- coding: utf-8 -*- # SPDX-FileCopyrightText: 2023 kaliko # 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