Rewrite documentation in more user-friendly way

Rewrite the PTGbot documentation so that it's more
user-friendly, and point users to it in case of errors.

Change-Id: I1ebe6fcc106c6e22ab004e27d38c81265d413603
This commit is contained in:
Thierry Carrez 2017-12-22 17:27:10 +01:00
parent d57f89dcb9
commit 648d1bf395
2 changed files with 85 additions and 35 deletions

View File

@ -4,13 +4,14 @@ OpenStack PTG Bot
ptgbot is the bot that PTG track moderators use to surface what's
currently happening at the event. Track moderators send messages to
the bot, like::
the bot, and from that information the bot builds a static webpage
with several sections of information:
#swift now discussing ring balancing
* The discussion topics currently discussed ("now")
* An indicative set of discussion topics coming up next ("next")
* The tracks pre-scheduled for the day
* The tracks which booked available slots in the additional rooms
and from that information the bot builds a static webpage with discussion
topics currently discussed ("now") and an indicative set of discussion
topics coming up next ("next").
Track moderators commands
=========================
@ -18,43 +19,92 @@ Track moderators commands
You have to have voice in the channel (+v) to send commands to the ptgbot.
Commands follow the following format::
#TRACK [now|next] TOPIC
#TRACK color CSS_COLOR_SPECIFIER
#TRACK book SLOT_REFERENCE
#TRACKNAME COMMAND [PARAMETERS]
Please note that:
Here is the list of available commands.
* There can only be one "now" discussion topic at a time. If multiple
topics are discussed at the same time in various corners of the room,
they should all be specified in a single "now" command.
now
---
* In order to ensure that information is current, entering a "now" command
wipes out any "next" entry for the same topic. You might want to refresh
those after entering a "now" topic.
* The color command only sets the background color for the track
name. The foreground is always white. Colors can be specified in any
form supported by the CSS attribute background-color.
Example::
The ``now`` command indicates the current topic of discussion in a given
track. Example usage::
#swift now discussing ring placement
#swift color blue
* Your track needs to exist in the system, and be scheduled in the day.
Information about the room will be added automatically from the schedule.
* You can mention other tracks by using the corresponding hashtags, like:
``#nova now discussing multi-attach with #cinder``.
* There can only be one ``now`` discussion topic at a time. If multiple
topics are discussed at the same time in various corners of the room,
they should all be specified in a single ``now`` command.
* In order to ensure that information is current, entering a ``now`` command
wipes out any ``next`` entry for the same track.
next
----
The ``next`` command lets you communicate the upcoming topics of discussion in
your track. You can use it as a teaser for things to come. Example usage::
#swift next at 2pm we plan to discuss #glance support
#swift next around 3pm we plan to cover cold storage features
...
#swift now discussing #glance support, come over!
#swift next at 3pm we plan to cover cold storage features
...
#oslo now discussing oslo.config drivers
#oslo location Level B, Ballroom A
* Your track needs to exist in the system, and be scheduled in the day.
* You can specify multiple ``next`` discussion topics. To clear the list, you
can enter a new ``now`` discussion topic, or use the ``clean`` command.
* Since passing a new ``now`` command wipes out the ``next`` entries, you
might want to refresh those after entering a ``now`` topic.
book
----
The ``book`` command is used to book available slots in the additional rooms.
Available time slots (at the bottom of the PTGbot page) display a slot code
you can use book the room. Example usage::
#vitrage book Missouri-MonAM
* Your track needs to exist in the system.
* Once you booked the slot, you are part of the schedule for the day, and
you can use the ``now`` and ``next`` commands to communicate what topic
is being discussed.
clean
-----
You can remove all ``now`` and ``next`` entries related to your track by
issuing the ``clean`` command (with no argument). Example usage::
#ironic clean
color
-----
By default all tracks appear as blue badges on the page. You can set your
own color using the ``color`` command. Colors can be specified in any
form supported by the CSS attribute background-color::
#infra color red
#oslo color #42f4c5
#oslo next after lunch we plan to discuss auto-generating config reference docs
You can also remove all entries related to your track by issuing the following
command::
* The color command only sets the background color for the track
name. The foreground is always white.
#TRACK clean
location
--------
The room your track discussions happen in should be filled automatically
by the PTGbot by looking up the schedule information. In case it's not right,
you can overwrite it using the ``location`` command. Example usage::
#oslo location Level B, Ballroom A
Admin commands

View File

@ -39,6 +39,7 @@ except ImportError:
# ^ This is why pep8 is a bad idea.
irc.client.ServerConnection.buffer_class.errors = 'replace'
ANTI_FLOOD_SLEEP = 2
DOC_URL = 'https://git.openstack.org/cgit/openstack/ptgbot/tree/README.rst'
class PTGBot(irc.bot.SingleServerIRCBot):
@ -89,9 +90,8 @@ class PTGBot(irc.bot.SingleServerIRCBot):
self.identify_msg_cap = True
def usage(self, channel):
self.send(channel,
"Format is '#TRACK [ now ... | next ... "
"| location ... | clean ]'")
self.send(channel, "Format is '#TRACK COMMAND [PARAMETERS]'")
self.send(channel, "See doc at: " + DOC_URL)
def send_track_list(self, channel):
tracks = self.data.list_tracks()