Copy sitedocs for fmn.web.

roles/notifs-frontend/files/about.rst

@@ -0,0 +1,111 @@
+Fedora Notifications
+====================
+
+Fedora Notifications is a family of systems built to manage end-user
+notifications triggered by `fedmsg <http://fedmsg.com>`_, the fedora FEDerated
+MeSsaGe bus.
+
+The wins here are:
+
+- Diverse kinds of notification media: Some users don't want email. At present
+  we can do notifications over email and IRC privmsg. In the future we hope to
+  add Android push notifications, desktop popups, and websocket integration
+  across all of our apps.
+- A single place for end-users to manage notification preferences: As it stands
+  right now, you have to update notification preferences (if you can do so at
+  all) in many different apps in many different places. (bodhi, koji, pkgdb,
+  etc..). With this app (Fedora Notifications), you can choose what you do and
+  don't want to receive in one place -- right here.
+
+- A single place for email code to live -- instead of being duplicated in every
+  application that we write and deploy. This will ostensibly reduce the amount
+  of code that the infrastructure team has to maintain.
+
+----
+
+In a nutshell, here's the way this application works:
+
+- You login and set up some preferences here, in this webapp.
+- Events occur in Fedora Infrastructure and are broadcast over fedmsg.
+- This application receives those events and compares them against your
+  preferences. If there's a match, then it forwards you a notification.
+
+We maintain a `lot of applications <https://apps.fedoraproject.org>`_. Over
+time, there has been an initiative to get them all speaking a similar language
+on the backend with fedmsg. Take a look at the `list of fedmsg topics
+<http://fedmsg.com/en/latest/topics/>`_ to see what all is covered.
+
+Some Terminology
+================
+
+Rule
+----
+
+This is smallest, most atomic object in the Fedora Notifications system. It is
+a simple rule that can be applied to a fedmsg message. It can evaluate to
+``True`` or ``False``.
+
+It has a name and a description. Some examples of rules are:
+
+- "is a *bodhi* message"
+- "is a *wiki edit* message"
+- "relates to the user *lmacken*"
+- "relates to the package *nethack*"
+- "relates to a package *owned by me in pkgdb*"
+
+We have a long list of rules defined. You'll see them when you go to set up
+your first filter
+
+Filter
+------
+
+To craft your preferences, you will build filters out of rules. Filters have a
+name (that you give them). An example could be something like:
+
+- My bodhi packager filter
+
+  - "is a bodhi message"
+  - "relates to a package that I own"
+
+You will receive notifications for this filter *if and only if* a given message
+**both** is a bodhi message and is about a package owned by you.
+
+----
+
+Note that, if you wanted to get notifications about bodhi updates created by
+multiple users, you would need to create distinct filters for each one.
+
+- My bodhi lmacken filter
+
+  - "is a bodhi message"
+  - "relates to the user **lmacken**"
+
+- My bodhi toshio filter
+
+  - "is a bodhi message"
+  - "relates to the user **toshio**"
+
+You could not combine those both into the same filter, because *all rules on a
+filter* must evalulate to ``True`` for the filter to trigger a notification.
+
+Messaging Context
+-----------------
+
+This is the medium over which we'll send a message. You can have one set of
+preferences for an email messaging context, and another set of preferences for
+an irc messaging context.
+
+When a fedmsg message arrives in the system, if *any one filter* on one of your
+messaging contexts evaluates to ``True``, then you will receive a notification
+for that context. If some filters evaluate to ``True`` for multiple contexts,
+you will receive notifications for all those contexts.
+
+Dénouement
+==========
+
+You can report `issues
+<https://github.com/fedora-infra/fmn/issues>`_ and find the
+`source <https://github.com/fedora-infra/fmn/>`_ on github.
+The development team hangs out in ``#fedora-apps``. Please do stop by and say
+hello.
+

roles/notifs-frontend/tasks/main.yml

@@ -24,3 +24,12 @@
   - fmn.web.conf
   notify:
   - restart apache
+
+- name: create live docs directory
+  file: >
+    dest=/usr/lib/python2.6/site-packages/fmn/web/docs/
+    state=directory
+
+- name: copy live docs
+  copy: src=$item dest=/usr/lib/python2.6/site-packages/fmn/web/docs
+  with_fileglob: fedora-sitedocs/*.rst