Build a list of available topics from known schema packages

Fixes: fedora-infra#226

Signed-off-by: Aurélien Bompard <aurelien@bompard.org>

docs/build-schemas-list.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+
+import os
+import tempfile
+import sys
+import venv
+import site
+from subprocess import run
+from collections import defaultdict
+from dataclasses import dataclass
+from textwrap import wrap
+
+
+SCHEMAS_FILE = "schema-packages.txt"
+DOC_FILE = "schemas.rst"
+HEADER = """
+=================
+Available Schemas
+=================
+
+.. This file is autogenerated by the build-schemas-list.py script. Do not edit manually.
+
+These are the topics that you can expect to see on Fedora's message bus,
+sorted by the python package that contains their schema.
+Install the corresponding python package if you want to make use of the schema
+and access additional information on the message you're receiving.
+"""
+
+
+def read_packages(schemas_filepath):
+    packages = []
+    with open(schemas_filepath, "r") as schemas_file:
+        for line in schemas_file:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            packages.append(line)
+    packages.sort()
+    return packages
+
+
+@dataclass
+class Schema:
+    topic: str
+    package: str
+    doc: str
+
+
+def create_venv(dirname):
+    venv.create(dirname, with_pip=True)
+    # Activate venv
+    sys.prefix = sys.exec_prefix = dirname
+    site.addsitepackages(None, [dirname])
+
+
+def install_packages(dirname, packages):
+    # Don't use pip as a library:
+    # https://pip.pypa.io/en/stable/user_guide/#using-pip-from-your-program
+    pip = os.path.join(dirname, "bin", "pip")
+    for package in packages:
+        run([pip, "install", package], check=True)
+
+
+def get_schemas():
+    import pkg_resources
+
+    schemas = defaultdict(list)
+    for entry_point in pkg_resources.iter_entry_points("fedora.messages"):
+        msg_cls = entry_point.load()
+        if not msg_cls.topic:
+            continue
+        package_name = entry_point.dist.project_name
+        doc = " ".join(wrap(msg_cls.__doc__)) if msg_cls.__doc__ else None
+        schemas[package_name].append(
+            Schema(topic=msg_cls.topic, package=package_name, doc=doc)
+        )
+    return schemas
+
+
+def write_doc(schemas, doc_filepath):
+    with open(doc_filepath, "w") as doc_file:
+        doc_file.write(HEADER)
+        for package_name in sorted(schemas):
+            package_schemas = schemas[package_name]
+            print(f"\n\n{package_name}", file=doc_file)
+            print("=" * len(package_name), end="\n\n", file=doc_file)
+            for schema in package_schemas:
+                if schema.doc:
+                    print(f"* ``{schema.topic}``: {schema.doc.strip()}", file=doc_file)
+                else:
+                    print(f"* ``{schema.topic}``", file=doc_file)
+
+
+def main():
+    packages = read_packages(SCHEMAS_FILE)
+    with tempfile.TemporaryDirectory() as tmpdirname:
+        create_venv(tmpdirname)
+        install_packages(tmpdirname, packages)
+        schemas = get_schemas()
+        write_doc(schemas, DOC_FILE)
+        print(f"Wrote the documentation in {DOC_FILE}")
+
+
+if __name__ == "__main__":
+    main()

docs/index.rst

@@ -25,6 +25,7 @@ User Guide
    consuming
    messages
    testing
+   schemas
    changelog
 
 

docs/schema-packages.txt

@@ -0,0 +1,10 @@
+# This file contains the list of known schema packages
+
+anitya-schema
+bodhi-messages
+fedocal-messages
+fedora-messaging-the-new-hotness-schema
+fedora-planet-messages
+noggin-messages
+git+https://github.com/fedora-infra/fedorainfra-ansible-messages.git@master
+git+https://github.com/fedora-infra/nuancier-messages.git@dev

docs/schemas.rst

@@ -0,0 +1,106 @@
+
+=================
+Available Schemas
+=================
+
+.. This file is autogenerated by the build-schemas-list.py script. Do not edit manually.
+
+These are the topics that you can expect to see on Fedora's message bus,
+sorted by the python package that contains their schema.
+Install the corresponding python package if you want to make use of the schema
+and access additional information on the message you're receiving.
+
+
+anitya-schema
+=============
+
+* ``org.release-monitoring.prod.anitya.distro.add``: Message sent by Anitya to the "anitya.distro.add" topic when a new     distribution is added.
+* ``org.release-monitoring.prod.anitya.distro.edit``: Message sent by Anitya when a distribution is edited.
+* ``org.release-monitoring.prod.anitya.distro.remove``: Message sent by Anitya when a distribution is removed.
+* ``org.release-monitoring.prod.anitya.project.add``: The message sent when a new project is created in Anitya.
+* ``org.release-monitoring.prod.anitya.project.edit``: The message sent when a project is edited in Anitya.
+* ``org.release-monitoring.prod.anitya.project.flag``: Sent when a new flag is created for a project.
+* ``org.release-monitoring.prod.anitya.project.flag.set``: Sent when a flag is closed for a project.
+* ``org.release-monitoring.prod.anitya.project.map.new``
+* ``org.release-monitoring.prod.anitya.project.map.remove``
+* ``org.release-monitoring.prod.anitya.project.map.update``
+* ``org.release-monitoring.prod.anitya.project.remove``: The message sent when a project is deleted in Anitya.
+* ``org.release-monitoring.prod.anitya.project.version.remove``
+* ``org.release-monitoring.prod.anitya.project.version.update``
+* ``org.release-monitoring.prod.anitya.project.version.update.v2``
+
+
+bodhi-messages
+==============
+
+* ``bodhi.buildroot_override.tag``: Sent when a buildroot override is added and tagged into the build root.
+* ``bodhi.buildroot_override.untag``: Sent when a buildroot override is untagged from the build root.
+* ``bodhi.compose.complete``: Sent when a compose task completes.
+* ``bodhi.compose.composing``: Sent when the compose task composes.
+* ``bodhi.compose.start``: Sent when a compose task starts.
+* ``bodhi.compose.sync.done``: Sent when a compose task sync is done.
+* ``bodhi.compose.sync.wait``: Sent when a compose task sync is waiting.
+* ``bodhi.errata.publish``: Sent when an errata is published.
+* ``bodhi.repo.done``: Sent when a repo is created and ready to be signed or otherwise processed.
+* ``bodhi.update.comment``: Sent when a comment is made on an update.
+* ``bodhi.update.complete.stable``: Sent when an update is available in the stable repository.
+* ``bodhi.update.complete.testing``: Sent when an update is available in the testing repository.
+* ``bodhi.update.edit``: Sent when an update is edited.
+* ``bodhi.update.eject``: Sent when an update is ejected from the push.
+* ``bodhi.update.karma.threshold.reach``: Sent when an update reaches its karma threshold.
+* ``bodhi.update.request.obsolete``: Sent when an update is requested to be obsoleted.
+* ``bodhi.update.request.revoke``: Sent when an update is revoked.
+* ``bodhi.update.request.stable``: Sent when an update is submitted as a stable candidate.
+* ``bodhi.update.request.testing``: Sent when an update is submitted as a testing candidate.
+* ``bodhi.update.request.unpush``: Sent when an update is requested to be unpushed.
+* ``bodhi.update.requirements_met.stable``: Sent when all the update requirements are meant for stable.
+* ``bodhi.update.status.testing.koji-build-group.build.complete``: Sent when an update is ready to be tested.
+
+
+fedocal-messages
+================
+
+* ``fedocal.calendar.clear``: A sub-class of a Fedora message that defines a message schema for messages     published by fedocal when a calendar is cleared.
+* ``fedocal.calendar.delete``: A sub-class of a Fedora message that defines a message schema for messages     published by fedocal when a calendar is deleted.
+* ``fedocal.calendar.new``: A sub-class of a Fedora message that defines a message schema for messages     published by fedocal when a calendar is created.
+* ``fedocal.calendar.update``: A sub-class of a Fedora message that defines a message schema for messages     published by fedocal when a calendar is updated.
+* ``fedocal.calendar.upload``: A sub-class of a Fedora message that defines a message schema for messages     published by fedocal when meetings have been uploaded into the calendar.
+* ``fedocal.meeting.delete``: A sub-class of a Fedora message that defines a message schema for messages     published by fedocal when a meeting is deleted.
+* ``fedocal.meeting.new``: A sub-class of a Fedora message that defines a message schema for messages     published by fedocal when a meeting is created.
+* ``fedocal.meeting.reminder``: A sub-class of a Fedora message that defines a message schema for messages     published by fedocal when a reminder is sent.
+* ``fedocal.meeting.update``: A sub-class of a Fedora message that defines a message schema for messages     published by fedocal when a meeting is updated.
+
+
+fedora-messaging-the-new-hotness-schema
+=======================================
+
+* ``org.fedoraproject.prod.hotness.update.bug.file``: Message sent by the-new-hotness to "hotness.update.bug.file" topic when     bugzilla issue is filled.
+* ``org.fedoraproject.prod.hotness.update.drop``: Message sent by the-new-hotness to "hotness.update.drop" topic when update     is dropped.
+
+
+fedora-planet-messages
+======================
+
+* ``org.fedoraproject.prod.planet.post.new``: The message sent when a new post is published in planet.
+
+
+fedorainfra-ansible-messages
+============================
+
+* ``ansible.playbook.complete``: Defines the message that is sent when an Ansible Playbook completes
+* ``ansible.playbook.start``: Defines the message that is sent when an Ansible Playbook starts
+* ``git.receive``: Defines the message that is sent when an Ansible Playbook starts
+
+
+noggin-messages
+===============
+
+* ``fas.group.member.sponsor``: The message sent when a user is added to a group by a sponsor
+* ``fas.user.create``: The message sent when a user is created
+* ``fas.user.update``: The message sent when a user is updated
+
+
+nuancier-messages
+=================
+
+* ``nuancier.new``: A sub-class of a Fedora message that defines a message schema for messages     published by nuancier when a new thing is created.