--- a/INSTALL	Wed Jun 12 21:51:50 2019 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,150 +0,0 @@
-Requirements
-============
-
-- Python 2.7.x
-- Twisted >= 15.2.0:
-   - Twisted Core
-   - Twisted Words
-- Wokkel >= 0.7.1 (http://wokkel.ik.nu/)
-- A XMPP server that supports the component protocol (XEP-0114),
-  and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355)
-  and privileged entity (XEP-0356) are needed.
-  We recommend using Prosody with mod_privilege and mod_delegation modules.
-- SàT backend (http://repos.goffi.org/sat) is currently needed for MAM and RSM handling
-
-For the PostgreSQL backend, the following is also required:
-
-- PostgreSQL >= 9.5 (including development files for psycopg2)
-- psycopg2
-
-
-Installation
-============
-
-sat_pubsub uses setuptools for package building and installing.
-To build from the source run:
-
-  python setup.py build
-
-Then, to install run the following, possibly as root:
-
-  python setup.py install
-
-See the setuptools documentation for further information on changing
-installation locations.
-
-
-Configuration
-=============
-
-sat_pubsub uses Twisted's twistd command for running its services.
-
-Idavoll, on which sat_pubsub is based, provides two types of storage for the backend:
-a memory-based storage facility, which is volatile, and a persistent storage facility
-using PostgreSQL. For now, sat_pubsub only uses the persistent storage facility.
-
-For using the PostgreSQL backend, create a database (for example named pubsub):
-
-  sudo -u postgres createuser -d -P `whoami`
-  createdb pubsub
-  psql pubsub < sat_pubsub/db/pubsub.sql
-
-
-Your XMPP server must also be configured to accept component connections and,
-to enable the micro-blogging feature, privileged entity and namespace delegation.
-See below for details.
-
-
-Running sat_pubsub
-==================
-
-The minimal example for running sat_pubsub is:
-
-  twistd sat_pubsub
-
-This will start the service and run it in the background. It generates a
-file twistd.pid that holds the PID of the service and a log file twistd.log.
-The twistd utility has a fair number of options that might be useful, and
-can be viewed with:
-
-  twistd --help
-
-When the service starts, it will connect to the XMPP server at the local
-machine using the component protocol, and assumes the JID 'pubsub'. This
-assumes a couple of defaults which can be overridden by passing parameters to
-the twistd plugin. You can get an overview of the parameters and their defaults
-using:
-
-  twistd sat_pubsub --help
-
-In particular, the following parameters will be of interest:
-
- --jid: The Jabber ID the component will assume.
- --rport: the port number of the XMPP server to connect to
- --secret: the secret used to authenticate with the XMPP server.
-
-For example:
-
-  twistd sat_pubsub --jid=sat-pubsub.<your_xmpp_domain> --secret=<password>
-
-You may also want to provide the --verbose flag to see the traffic flow,
-for example to debug the configuration. Below some specifics for the
-Prosody XMPP server implementation.
-
-
-Running sat_pubsub with Prosody
-===============================
-
-To enable the micro-blogging feature with Prosody XMPP server, you need
-the mod_delegation and privileged_entity plugins.
-Check if the mod_delegation and mod_privilege plugins are already
-in your Prosody installation:
-
-  cd prosody/plugins
-  ls mod_delegation.lua
-  ls mod_privilege.lua
-
-If you can't see it, download them from http://modules.prosody.im:
-
-  wget http://hg.prosody.im/prosody-modules/raw-file/tip/mod_delegation/mod_delegation.lua
-  wget http://hg.prosody.im/prosody-modules/raw-file/tip/mod_privilege/mod_privilege.lua
-
-Edit the prosody.cfg.lua file to add this module:
-
-  modules_enabled = {
-                [...]
-                "delegation";
-                "privilege";
-                [...]
-  }
-
-In your VirtualHost, add this lines:
-
-VirtualHost "<your_xmpp_domain>"
-  privileged_entities = {
-    ["sat-pubsub.<your_xmpp_domain>"] = {
-      roster = "get";
-      message = "outgoing";
-    },
-  }
-  delegations = {
-    ["urn:xmpp:mam:1"] = {
-      filtering = {"node"};
-      jid = "sat-pubsub.<your_xmpp_domain>";
-    },
-    ["http://jabber.org/protocol/pubsub"] = {
-      jid = "sat-pubsub.<your_xmpp_domain>";
-    },
-  }
-
-Also add these two lines at the end of the file, adapting them to your XMPP server
-domain (virtual host) and selecting a password of your choice:
-
-  Component "sat-pubsub.<your_xmpp_domain>"
-          component_secret = "<password>"
-		  modules_enabled = {"delegation", "privilege"}
-
-For a more complete installation and configuration of Prosody to be used with
-sat_pubsub, please report yourself to the Salut à Toi wiki:
-
-http://wiki.goffi.org/wiki/Libervia/en#XMPP_server

--- a/README	Wed Jun 12 21:51:50 2019 +0200
+++ b/README	Wed Jul 24 19:26:43 2019 +0200
@@ -5,9 +5,7 @@
 Copyright (c) 2014-2016 Adrien Cossa
 Copyright (c) 2003-2011 Ralph Meijer
 
-Sàt PubSub is a PubSub component service for XMPP
-
-
+SàT PubSub is a PubSub component service for XMPP
 
 
 ** LICENSE **
@@ -29,14 +27,14 @@
 ** ABOUT **
 
 SàT PubSub is a XMPP PubSub service component (XEP-0060)
-It's based on Ralph Meijer's Idavoll, but provide special features necessary for the « Salut à Toi » project ( http://sat.goffi.org ), but it can also be used for any other XMPP project.
+It's based on Ralph Meijer's Idavoll, and provides special features necessary for the « Salut à Toi » project (https://salut-a-toi.org), but it can also be used for any other XMPP project.
 The use of a standard external component allow to use this features with most XMPP servers.
-One of the main addition is fine access tuning for PubSub, which allow the publication of items for only some groups, even if the entire node is open. The protocol is explained on http://www.goffi.org/post/2012/06/24/Fine-access-tuning-for-PubSub for the moment, and a protoxep should be proposed to the XSF in the future...
+One of the main addition is fine access tuning for PubSub, which allow the publication of items for only some groups, even if the entire node is open. The protocol is explained on https://www.goffi.org/post/2012/06/24/Fine-access-tuning-for-PubSub for the moment, and a protoxep should be proposed to the XSF in the future...
 
 
 ** INSTALLATION **
 
-Instructions for installation are the same as for Idavoll, so follow what is written in INSTALL and UPGRADING files.
+Please check doc/ directory
 
 
 ** CREDIT **

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Makefile	Wed Jul 24 19:26:43 2019 +0200
@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = .build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py	Wed Jul 24 19:26:43 2019 +0200
@@ -0,0 +1,173 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = u'SàT PubSub'
+copyright = u'2019, Jérôme Poisson'
+author = u'Jérôme Poisson'
+
+# The short X.Y version
+version = u''
+# The full version, including alpha/beta/rc tags
+release = u'0.3.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [u'.build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# 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
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['.static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'STPubSubdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'STPubSub.tex', u'SàT PubSub Documentation',
+     u'Jérôme Poisson', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'stpubsub', u'SàT PubSub Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'STPubSub', u'SàT PubSub Documentation',
+     author, 'STPubSub', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/index.rst	Wed Jul 24 19:26:43 2019 +0200
@@ -0,0 +1,31 @@
+.. SàT PubSub documentation master file, created by
+   sphinx-quickstart on Wed Jul 24 08:06:59 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+SàT PubSub documentation
+========================
+
+SàT PubSub is a XMPP PubSub service component (XEP-0060) It's based on Ralph Meijer's
+Idavoll, and provides special features necessary for the « Salut à Toi » project
+(https://salut-a-toi.org) , but it can also be used for any other XMPP project.  The use
+of a standard external component allow to use this features with most XMPP servers.  One
+of the main addition is fine access tuning for PubSub, which allow the publication of
+items for only some groups, even if the entire node is open. The protocol is explained on
+http://www.goffi.org/post/2012/06/24/Fine-access-tuning-for-PubSub for the moment, and a
+protoxep should be proposed to the XSF in the future…
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   installation.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/installation.rst	Wed Jul 24 19:26:43 2019 +0200
@@ -0,0 +1,210 @@
+============
+Installation
+============
+
+This are the instructions to install SàT Pubsub.
+
+Please note that SàT PubSub, as all SàT ecosystem, is still using Python 2 (this will
+change for 0.8 version which will be Python 3 only), so all instructions below have to be
+made using python 2.
+
+.. note::
+
+   SàT PubSub is not released yet and this documentation is work in progress
+
+
+Requirements
+------------
+
+- Python 2.7.x
+- Twisted >= 15.2.0:
+   - Twisted Core
+   - Twisted Words
+- Wokkel >= 0.7.1 (http://wokkel.ik.nu/)
+- A XMPP server that supports the component protocol (XEP-0114),
+  and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355)
+  and privileged entity (XEP-0356) are needed.
+  We recommend using Prosody with mod_privilege and mod_delegation modules (those modules
+  are maintained by us).
+- SàT tmp (http://repos.goffi.org/sat_tmp) is currently needed for MAM and RSM handling
+
+For the PostgreSQL backend, the following is also required:
+
+- PostgreSQL >= 9.5 (including development files for psycopg2)
+- psycopg2
+
+Installation From Sources
+-------------------------
+
+.. note::
+
+   The installation script is not up-to-date (notably requirements). The situation should
+   improve soon.
+
+To install SàT PubSub we'll work in a virtual environment. On Debian and derivatives you
+should easily install dependencies with this::
+
+    sudo apt-get install postgresql python-psycopg2 python-dev mercurial virtualenv
+
+Now go in a location where you can install SàT Pubsub, for instance your home directory::
+
+    $ cd
+
+And enter the following commands (note that *virtualenv2* may be named
+*virtualenv* on some distributions, just be sure it's Python **2** version)::
+
+    $ virtualenv2 env
+    $ source env/bin/activate
+    $ pip install uuid twisted wokkel psycopg2 sat_tmp
+    $ pip install hg+https://repos.goffi.org/sat_pubsub
+
+Post Installation
+-----------------
+
+Once SàT Pubsub is installed, you'll need to create a PostgreSQL user, and create the
+database::
+
+    % sudo -u postgres createuser -d -P $(whoami)
+    % createdb pubsub
+    % cd /tmp && wget https://repos.goffi.org/sat_pubsub/raw-file/tip/db/pubsub.sql
+    % psql pubsub < pubsub.sql
+
+
+.. _prosody_configuration:
+
+Prosody Configuration
+---------------------
+
+SàT PubSub can work with any XMPP server (which supports components), but if you want to
+use it as your PEP service, you need a server which supports `XEP-0355`_ and `XEP-0356`_.
+
+Below you'll find the instruction to use SàT PubSub as a PEP service with Prosody:
+
+-  add these two lines at the end of your ``prosody.cfg.lua`` file, adapting them to your XMPP
+   server domain (virtual host) and selecting a password of your choice:
+
+.. sourcecode:: lua
+
+    Component "sat-pubsub.<xmpp_domain>"
+            component_secret = "<password>"
+
+-  there are extra steps to enable the micro-blogging feature with Prosody. Please follow
+   the installation and configuration instructions that are given on these pages:
+
+   - https://modules.prosody.im/mod_delegation.html
+   - https://modules.prosody.im/mod_privilege.html
+
+To keep your modules up to date, we recommend to clone the full modules
+repository and then to symlink them like that:
+
+.. sourcecode:: shell
+
+    % cd /path/to/install_dir
+    % hg clone https://hg.prosody.im/prosody-modules
+    % cd /path/to/prosody_plugins
+    % ln -sf /path/to/install_dir/prosody-modules/mod_delegation ./
+    % ln -sf /path/to/install_dir/prosody-modules/mod_privilege ./
+
+Or course, you have to adapt ``/path/to/install_dir`` to the directory where you want to
+install the modules, and ``/path/to/prosody_plugins`` to the directory where prosody
+modules are installed (hint: check ``prosodyctl about`` to find the latter). The ``ln``
+commands may have to be run as root depending on your installation.
+
+Once your symlinks are set, to update the modules we just need to type this:
+
+.. sourcecode:: shell
+
+    % cd /path/to/install_dir/prosody-modules
+    % hg pull -u
+
+Here is an example of how your ``prosody.cfg.lua`` should look like with
+``mod_delegation`` and ``mod_privilege`` activated:
+
+.. sourcecode:: lua
+
+    [...]
+    modules_enabled = {
+                  [...]
+                  "delegation";
+                  "privilege";
+    }
+    [...]
+    VirtualHost "<xmpp_domain>"
+      privileged_entities = {
+        ["sat-pubsub.<xmpp_domain>"] = {
+          roster = "get";
+          message = "outgoing";
+          presence = "roster";
+        },
+      }
+      delegations = {
+          ["urn:xmpp:mam:2"] = {
+            filtering = {"node"};
+            jid = "sat-pubsub.<xmpp_domain>";
+          },
+          ["http://jabber.org/protocol/pubsub"] = {
+            jid = "sat-pubsub.<xmpp_domain>";
+          },
+          ["http://jabber.org/protocol/pubsub#owner"] = {
+            jid = "sat-pubsub.<xmpp_domain>";
+          },
+          ["https://salut-a-toi/protocol/schema:0"] = {
+            jid = "sat-pubsub.<xmpp_domain>";
+          },
+          ["http://jabber.org/protocol/disco#items:*"] = {
+            jid = "sat-pubsub.<xmpp_domain>";
+          },
+          ["https://salut-a-toi.org/spec/pubsub_admin:0"] = {
+            jid = "sat-pubsub.<xmpp_domain>";
+          },
+      }
+
+    Component "sat-pubsub.<xmpp_domain>"
+       component_secret = "<password>"
+       modules_enabled = {"delegation", "privilege"}
+
+Of course, you still have to replace and adapt to your own settings.
+
+.. _XEP-0355: https://xmpp.org/extensions/xep-0355.html
+.. _XEP-0356: https://xmpp.org/extensions/xep-0356.html
+
+Running SàT PubSub
+------------------
+
+The minimal example for running sat_pubsub is:
+
+  % twistd sat_pubsub
+
+This will start the service and run it in the background. It generates a
+file twistd.pid that holds the PID of the service and a log file twistd.log.
+The twistd utility has a fair number of options that might be useful, and
+can be viewed with:
+
+  % twistd --help
+
+When the service starts, it will connect to the XMPP server at the local machine using the
+component protocol, and assumes the JID ``pubsub``. This assumes a couple of defaults
+which can be overridden by passing parameters to the twistd plugin. You can get an
+overview of the parameters and their defaults using:
+
+  % twistd sat_pubsub --help
+
+In particular, the following parameters will be of interest:
+
+ ``--jid``
+    The Jabber ID the component will assume.
+
+ ``--rport``
+    the port number of the XMPP server to connect to
+
+ ``--xmpp_pwd``
+    the secret used to authenticate with the XMPP server.
+
+For example::
+
+  twistd sat_pubsub --jid=sat-pubsub.<your_xmpp_domain> --xmpp_pwd=<password>
+
+You can set your options in ``sat.conf`` which is the same file used as for Salut à Toi
+ecosystem. Please check backend ``configuration`` section for details. The SàT PubSub
+options must be in ``[pubsub]`` section.
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/make.bat	Wed Jul 24 19:26:43 2019 +0200
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=.build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd