core, doc, cli (forums): new forums set commands + doc:

- document the fact that if an empty `uri` is used, the forum node is created
  automatically
- new `forums/set` CLI commands and its documentation

libervia/backend/plugins/plugin_misc_forums.py

@@ -17,6 +17,8 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+from typing import Iterable
+from libervia.backend.core.core_types import SatXMPPEntity
 from libervia.backend.core.i18n import _
 from libervia.backend.core.constants import Const as C
 from libervia.backend.core import exceptions
@@ -80,8 +82,15 @@ class forums(object):
                               method=self._create_topic,
                               async_=True)
 
-    @defer.inlineCallbacks
-    def _create_forums(self, client, forums, service, node, forums_elt=None, names=None):
+    async def _create_forums(
+            self,
+            client: SatXMPPEntity,
+            forums: list[dict],
+            service: jid.JID,
+            node: str,
+            forums_elt: domish.Element|None = None,
+            names: Iterable = None
+    ) -> domish.Element:
         """Recursively create <forums> element(s)
 
         @param forums(list): forums which may have subforums
@@ -111,10 +120,10 @@ class forums(object):
             for key, value in forum.items():
                 if key == 'name' and key in names:
                     raise exceptions.ConflictError(_("following forum name is not unique: {name}").format(name=key))
-                if key == 'uri' and not value.strip():
+                if key == 'uri' and value is None or not value.strip():
                     log.info(_("creating missing forum node"))
                     forum_node = FORUM_TOPICS_NODE_TPL.format(node=node, uuid=shortuuid.uuid())
-                    yield self._p.createNode(client, service, forum_node, self._node_options)
+                    await self._p.createNode(client, service, forum_node, self._node_options)
                     value = uri.build_xmpp_uri('pubsub',
                                              path=service.full(),
                                              node=forum_node)
@@ -123,8 +132,9 @@ class forums(object):
                 elif key in FORUM_SUB_ELTS:
                     forum_elt.addElement(key, content=value)
                 elif key == 'sub-forums':
+                    assert isinstance(value, list)
                     sub_forums_elt = forum_elt.addElement('forums')
-                    yield self._create_forums(client, value, service, node, sub_forums_elt, names=names)
+                    await self._create_forums(client, value, service, node, sub_forums_elt, names=names)
                 else:
                     log.warning(_("Unknown forum attribute: {key}").format(key=key))
             if not forum_elt.getAttribute('title'):
@@ -135,7 +145,7 @@ class forums(object):
                     raise ValueError(_("forum need a title or a name"))
             if not forum_elt.getAttribute('uri') and not forum_elt.children:
                 raise ValueError(_("forum need uri or sub-forums"))
-        defer.returnValue(forums_elt)
+        return forums_elt
 
     def _parse_forums(self, parent_elt=None, forums=None):
         """Recursivly parse a <forums> elements and return corresponding forums data