From: kaliko <kaliko@azylum.org>
Date: Wed, 13 May 2020 18:08:43 +0000 (+0200)
Subject: doc: Improved documentation
X-Git-Tag: 0.1.1~3
X-Git-Url: https://git.kaliko.me/?p=sid.git;a=commitdiff_plain;h=54565dde76562668aac0c6949619d8db040e3f67

doc: Improved documentation
---

diff --git a/README.rst b/README.rst
index 3bd1ca5..1d724e1 100644
--- a/README.rst
+++ b/README.rst
@@ -5,16 +5,22 @@ sid an xmpp bot
 Getting sid
 ------------
 
-Currently unreleased, only a development version is available.
+Currently unreleased on PyPi_.
+
+`git tagged` version and `master branch` should be stable though.
+
+* Doc:   https://kaliko.gitlab.io/sid/
+* git:   https://gitlab.com/kaliko/sid.git
+* Issue: https://gitlab.com/kaliko/sid/-/issues
 
-* doc: https://kaliko.gitlab.io/sid/
-* git: https://gitlab.com/kaliko/sid.git
-* issue: https://gitlab.com/kaliko/sid/-/issues
 
 Get the source with git::
 
   git clone git://git.kaliko.me/sid.git
 
+Install/update master from git::
+
+  pip install -U git+https://gitlab.com/kaliko/sid.git@master#egg=sid
 
 Using the bot
 -------------
@@ -29,9 +35,12 @@ Here is a plain example::
    from sid.ping import Ping
 
    JID = 'bot@example.org'
+   ROOM = 'room@conf.example.org'
+   # Pay attention: if you join the room with the same account/nick,
+   # For instance with a regular interactive client, the bot will
+   # not answer you, it ignores its own messages for obvious reasons.
    NICK = 'sid'
    PASS = getpass.getpass(f'Password for "{JID}": ')
-   ROOM = 'room@conf.example.org'
 
    # Instanciate the bot
    xmpp = MUCBot(JID, PASS, ROOM, NICK)
@@ -51,3 +60,5 @@ Contacting author
 
 The current maintainer can be found on xmpp chat room <kaliko.me⊘conf.azylum.org>
 or you can contact him by email/xmpp <kaliko⊘azylum.org>.
+
+.. _PyPI: https://pypi.org
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 0598e81..3f24004 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -34,7 +34,8 @@ release = ".".join(__version__.split(".")[0:2])
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+# need 2.0 at least for "autodecorator"
+needs_sphinx = '2.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -71,7 +72,7 @@ language = None
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
+pygments_style = 'sphinx'
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -79,8 +80,16 @@ pygments_style = None
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
 #html_theme = 'sphinx_rtd_theme'
+#html_theme_options = {
+#        'prev_next_buttons_location': 'both',
+#        'style_external_links': True,
+#        }
+html_theme = 'alabaster'
+html_theme_options = {
+         'donate_url': 'https://liberapay.com/kaliko/'
+         }
+html_show_sphinx = False
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
diff --git a/sid/log.py b/sid/log.py
index f3f45e7..e97e738 100644
--- a/sid/log.py
+++ b/sid/log.py
@@ -24,6 +24,9 @@ from .plugin import Plugin, botcmd
 
 class Log(Plugin):
     """Logs presence.
+
+    The account running the bot need at least room moderation right to log
+    participants JIDs (fallback to nickname).
     """
     throttle_ts = int(time())-30