/usr/share/pyshared/fedmsg/doc_utilities.py is in python-fedmsg 0.7.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 | #!/usr/bin/env python
# -*- coding: utf-8 -*-
""" Code to generate doc/topics.rst during 'sphinx-build'.
This code:
- Uses :mod:`nose` to find all the fedmsg.meta unittests.
- Extracts all the metadata and docstrings from those tests.
- Uses all that to generate a giant .rst document of all the fedmsg
topics and what they are about with example messages.
"""
import os
import nose
import pprint
import textwrap
header = """
List of Message Topics
======================
.. DO NOT EDIT THIS DOCUMENT.
.. It is autogenerated from extras/topics-doc/make-topics-doc.py
This document lists all the topics coming out the Fedora
Infrastructure fedmsg bus. Example messages are included
as well as descriptions and sample output from ``fedmsg.meta``.
.. note:: All topics from Fedora Infrastructure are prefixed with
``org.fedoraproject.prod.``, but the :term:`topic_prefix` is omitted here
for brevity. For instance, the item listed as ``git.branch`` will
actually be broadcast as ``org.fedoraproject.prod.git.branch``.
.. note:: Message bodies can contain some useful information, but be wary.
We have done as good a job as we can *securing* fedmsg, but it is still
a new system. If you receive a message from pkgdb claiming that "ralph"
is the new owner of the kernel, you should still *check* with the *actual*
pkgdb service that this is the case. Write code against fedmsg messages
as a tip, but always check the authoritative source before taking any
programmatic action.
"""
metadata_template = """
The example message above, when passed to various routines in the
:mod:`fedmsg.meta` module, will produce the following outputs:
- :func:`fedmsg.meta.msg2title`
- {title}
- :func:`fedmsg.meta.msg2subtitle`
- {subtitle}
- :func:`fedmsg.meta.msg2link`
- {link}
- :func:`fedmsg.meta.msg2icon`
- {icon}
- :func:`fedmsg.meta.msg2secondary_icon`
- {secondary_icon}
- :func:`fedmsg.meta.msg2usernames`
- ``{usernames}``
- :func:`fedmsg.meta.msg2packages`
- ``{packages}``
- :func:`fedmsg.meta.msg2objects`
- ``{objects}``
"""
outfile = None
def write(fname, s=''):
global outfile
if not outfile:
outfile = open(fname, 'w')
outfile.write(s + '\n')
def load_classes(folder):
return list(list(
nose.loader.defaultTestLoader().loadTestsFromDir(folder)
)[0])
def make_topics_doc(output_dir):
fname = output_dir + "/topics.rst"
global outfile
import fedmsg_meta_fedora_infrastructure
filename = fedmsg_meta_fedora_infrastructure.__file__
folder = os.path.sep + os.path.join(*filename.split('/')[:-1])
test_classes = load_classes(folder)
# TODO -- get the logger and announce messages
#import fedmsg
#filename = fedmsg.__file__
#folder = os.path.sep + os.path.join(*filename.split('/')[:-1])
#test_classes = load_classes(folder)
write(fname, header)
for cls in test_classes:
if cls.context.msg:
# Adjust {stg,dev} to prod.
cls.context.msg['topic'] = cls.context.msg['topic']\
.replace('.stg.', '.prod.')\
.replace('.dev.', '.prod.')
cls.context.expected_title = cls.context.expected_title\
.replace('.stg.', '.prod.')\
.replace('.dev.', '.prod.')
topic = '.'.join(cls.context.msg['topic'].split('.')[3:])
cls.__topic = topic
else:
cls.__topic = None
comparator = lambda a, b: cmp(a.__topic, b.__topic)
test_classes = sorted(test_classes, comparator)
seen = []
for cls in test_classes:
if cls.context.msg:
topic = cls.__topic
# Ignore tests that check old messages.
if 'Legacy' in cls.context.__name__:
continue
modname = topic.split('.')[0]
if not modname in seen:
seen.append(modname)
write(fname, modname)
write(fname, "-" * len(modname))
write(fname)
write(fname, topic)
write(fname, "~" * len(topic))
write(fname)
# I would use __doc__ here, but something that nose is doing is
# stripping the __doc__ from my original unit tests. Instead,
# we'll use our own 'doc' attribute which is a little clumsy.
if getattr(cls.context, 'doc', None):
write(fname, textwrap.dedent(" " + cls.context.doc.strip()))
write(fname)
write(fname, ".. code-block:: python")
write(fname, '\n ' + pprint.pformat(cls.context.msg, indent=2)
.replace('\n', '\n '))
write(fname)
write(fname, metadata_template.format(
link=cls.context.expected_link,
title=cls.context.expected_title,
subtitle=cls.context.expected_subti,
usernames=cls.context.expected_usernames,
packages=cls.context.expected_packages,
objects=cls.context.expected_objects,
icon=cls.context.expected_icon,
secondary_icon=cls.context.expected_secondary_icon,
))
write(fname)
outfile.close()
if __name__ == '__main__':
make_topics_doc()
|