From 7c36b6b89e1adec1f1c38fd312c88e5c220abc7c Mon Sep 17 00:00:00 2001 From: Richard Darst Date: Sat, 19 Sep 2009 19:00:15 +0000 Subject: Many manual updates - Reorganize Administratiors section. - Explain the meeting.py / supybot divide. - Document writer_map config variable and all writers. - Document replay functionality. - Fix other random errors. darcs-hash:20090919190015-82ea9-f6ad04b2311ea0dfe4737311b58b524e8485a37a.gz --- (limited to 'doc') diff --git a/doc/Manual.txt b/doc/Manual.txt index 5764a89..de6f1e2 100644 --- a/doc/Manual.txt +++ b/doc/Manual.txt @@ -284,61 +284,55 @@ Administrators Overview -------- +Unfortunately, MeetBot seems a bit complex to configure. In order to +keep things straight, keep this in mind: MeetBot has two distinct +pieces. The first (``meeting.py`` and friends) is the meeting parser +and note/logfile generator. This part can run independently, +*without* the supybot plugin. The second part interfaces the core +``meeting.py`` to supybot, to make it usable via IRC. +When reading about how to run MeetBot, keep this in mind, and if +something is applicable to ``meeting.py`` features, just supybot +features, or both. +This design split greatly increases modularity (a "good thing"), and +also allows the Replay functionality. It should also allow other bot +plugins to easily be written. -Supybot admin commands ----------------------- -These commands are for the bot owners to manage all meetings served by -their bot. The expected use of these commands is when the bot is on -many channels as a public service, and the bot owner sometimes needs -to be able to monitor and adjust the overall situation, even if she is -not the chair of a meeting. -All of these are regular supybot commands (as opposed to the commands -above). That means that the supybot capability system applies, and -they can be given either in any channel, either by direct address -(``BotName: ...``) or with the bot prefix character -(e.g. ``@ ...``). If there are commands with the -same name in multiple plugins, you need to prefix the command with the -plugin name (for example, ``BotName: meetbot recent`` instead of -``BotName: recent``) +Replay functionality +-------------------- -These are restricted to anyone with the ``admin`` capability on the -bot. +Let's say you had a meeting which happened a while ago, and you would +like to update the logs to a newer format. If supybot was the only +way to use MeetBot, you'd be out of luck. Luckily, there is an +independent way to replay meetings:: -``listmeetings`` - List all meetings. + python /path/to/meeting.py replay /path/to/old_meeting.log.txt -``savemeetings`` - Saves all active meetings on all channels and all networks. +You run the meeting.py file as a script, giving the subcommand +``replay`` and then a path to a ``.log.txt`` file from a previous +meeting (or from some other source of IRC logs, it's essentially the +irssi/xchat format). It parses it and processes the meeting, and +outputs all of the usual ``.html``, ``.log.html``, and so on files in +the directory parallel to the input file. -``addchair `` - Forcibly adds this nick as a chair on the giver channel on the given - network, if a meeting is active there. +This is useful if you want to upgrade your output formats, MeetBot +broke and you lost the realtime log and want to generate a summary +using your own logfiles, remove or change something in the logs that +was incorrect during the meeting. As such, this is an important +feature of MeetBot. -``deletemeeting `` - Delete a meeting from the cache. If save is given, save the meeting - first. The default value of ``save`` is True. This is useful for - when MeetBot becomes broken and is unable to properly save a - meeting, rendering the ``#endmeeting`` command non-functional. - -``recent`` - Display the last ten or so started meetings, along with their - channels. This is useful if you are the bot admin and want to see - just who all is using your bot, for example to better communicate - with those channels. - -To connect to multiple IRC networks, use the supybot ``Network`` -plugin to manage them. First, load the ``Network`` plugin, then use -the ``connect`` command to connect to the other network. Finally, you -need to tell supybot to join channels on the new. To do -that, you can use ``network command join ``. -(Alternatively, you can /msg the bot through the other network, but -you'll have to register your nick to it on the other network in order -for it to accept commands from you.) +However, this does make configuration changes harder. Since the +replay function works *independent* of supybot, any configuration that +is done in supybot will be invisible to the replay function. Thus, we +have to have a non-supybot mechanism of configuring MeetBot. There +was a supybot way of configuring MeetBot added later, which can adjust +most variables. However, if something is configured here, it won't be +seen if a file is replayed. This might be OK, or it might not be, +depending on the variable. @@ -346,6 +340,13 @@ for it to accept commands from you.) Configuration ------------- +meetingLocalConfig.py configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the non-supybot method of configuration, and allows the most +flexibility. **It works for configuring supybot, too**, but requires +shell access and a MeetBot reload to change. + Configuration is done by creating a file ``meetingLocalConfig.py`` in the plugin directory, or somewhere in your PYTHONPATH. It works by (automatically, not user-visible) subclassing the Config class. @@ -367,10 +368,12 @@ Two other more commonly used options are:: Place all of the configuration variables inside of the class body like this. -``meetingLocalConfig.py`` is a complete execution, and causes a -subclass of the main Config object. Thus, you can do some advanced -(or just crazy) things like add a new meeting command, meeting -agenda item type, or more. Not all of these are documented here. +``meetingLocalConfig.py`` is imported via python, so all the usual +benefits and caveats of that apply. It causes a subclass of the main +Config object. Thus, you can do some advanced (or just crazy) things +like add a new meeting command, meeting agenda item type, or more. +Some of these ideas are documented under the "Advanced configuration" +section below. To reload a configuration in a running supybot, you can just reload the plugin in supybot --- the module is reloaded. Specifically, @@ -381,10 +384,15 @@ the plugin in supybot --- the module is reloaded. Specifically, Supybot-based config ~~~~~~~~~~~~~~~~~~~~ -In addition to the normal ``meetingLocalConfig.py`` based -configuration, there is a mode where the supybot registry system can -be used to set the values of some configuration variables. To enable -this system, first the +This is the system that configures MeetBot based on the supybot +registry system. Thus, it can be adjusted by anyone with the proper +supybot capabilities. However, the configuration in the supybot +registry *won't* be used if the ``replay`` functionality is used (see +above). Thus, for example, if you configure the MediaWiki writer +using ``supybot.plugins.MeetBot.writer_map``, and then ``replay`` the +meeting, the MediaWiki output will *not* be updated. + +To enable this system, first the ``supybot.plugins.MeetBot.enableSupybotBasedConfig`` variable must be set to True. Then the MeetBot plugin must be reloaded:: @@ -405,11 +413,15 @@ Setting a value for a variable:: /msg YourBot config supybot.plugins.MeetBot.logUrlPrefix http://meetings.yoursite.net/ +Most variables (those with # prepended) can be set on a per-channel +basis (they are set up as channel-specific variables). + At present, not all variables are exported to supybot. All string and boolean variables are, as well certain other variables for which a -wrapper has been written. If a variable doesn't appear in the supybot -registry, it can't be set via the registry. +wrapper has been written (``writer_map`` in particular). If a +variable doesn't appear in the supybot registry, it can't be set via +the registry. If you want to disable supybot-based config for security reasons, set ``dontBotConfig`` to True in your custom configuration class in @@ -418,19 +430,19 @@ If you want to disable supybot-based config for security reasons, set Required or important configuration ------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These variables are set either in ``meetingLocalConfig.py`` (in the ``Config`` class) or in the supybot registry. ``logFileDir`` - The filesystem directory in which the meeting outputs are stored. - **Required** or supybot can't save properly. + The filesystem directory in which the meeting outputs are stored, + defaulting to ".". **Required**. ``logUrlPrefix`` The URL corresponding to ``logFileDir``. This is prepended to filenames when giving end-of-meeting links in the channel. - **Required** or supybot's URLs will be wrong. + **Required** or supybot's URLs will be missing. ``filenamePattern`` This defaults to ``'%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M'``, @@ -446,19 +458,119 @@ These variables are set either in ``meetingLocalConfig.py`` (in the This filename does *not* include extensions. Those are found from the writers, via the variable ``writer_map``. - Putting these all together, a set of variables could be: - 1) ``logFileDir = /srv/www/meetings/`` - 2) ``%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M`` - 3) (extensions come from ``writers_map``) +Putting these all together, a set of variables could be: + 1) ``logFileDir = /srv/www/meetings/`` + 2) ``%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M`` + 3) (``.html``, ``.txt``, etc, extensions come from ``writers_map``) ``MeetBotInfoURL`` This is a URL given in beginning and ending messages and minutes files as a "go here for more information" link. +writer_map configuration +~~~~~~~~~~~~~~~~~~~~~~~~ + +``writer_map`` tells how we want to output the results of the meeting. +It is, as you can guess, a mapping from filename extensions +(``.html``, ``.log.html``, ...) to what we want to output to that file +(``writers.HTML``, ``writers.HTMLlog``, ...) + +Using ``meetingLocalConfig.py``, it is python dictionary listing what +output formats will be used to write our final results to a file, +along with extensions to use. For example, in +``meetingLocalConfig.py``:: + + import writers + + class Config: + writer_map = { + '.log.html':writers.HTMLlog, + '.html': writers.HTML, + '.txt': writers.RST, + '.mw':writers.MediaWiki, + } + + +This *can* be configured through supybot. To do this, set +``supybot.plugins.MeetBot.writer_map`` to a space-separated list of +``WriterName:.extension`` pairs (note the different ordering from the +python dictionary). For example, to list the current setting (in +private message with the bot):: + + config plugins.MeetBot.writer_map + HTML2:.html MediaWiki:.mw HTMLlog2:.log.html Text:.txt + +And to set it (again, in private message with the bot):: + + config plugins.MeetBot.writer_map HTML2:.html MediaWiki:.mw HTMLlog2:.log.html Text:.txt + + + + +The available writers are (with default extensions, if enabled by +default): + +``TextLog`` (``.log.txt``) + Plain-text logs suitable for replaying. This does **not** have to + be explicitly enabled listed-- it is automatically enabled + whenever it is needed (currently, only when a meeting comes + realtime from supybot, not when being replayed) + +``HTMLlog`` (``.log.html``) + Alias for the current default HTML-pretty logs output format, + currently ``HTMLlog2``. + +``HTMLlog2`` + Writes the logs in a HTML-pretty, CSS-customizable way (see section + below). + +``HTML`` (``.html``) + Alias for the current default HTML output format for the meeting + notes, currently ``HTML2``. + +``HTML2`` + Meeting notes, in a numbered list HTML output format. + Configurable via CSS (see section below). + +``Text`` (``.txt``) + A meeting notes format, as a plain text file + +``MediaWiki`` + MediaWiki output. This doesn't upload *to* a MediaWiki instance, + but that could be added later. + +``PmWiki`` + PmWiki output. This doesn't upload *to* a PmWiki instance, + but that could be added later. + +Obsolete writers are: + +``HTMLlog1`` + Old HTML writer. This one requires the Python module ``pygments`` + to be installed. HTMLlog2 was written to remove this dependency. + HTMLlog2 is just as pretty as this is, and HTMLlog2 is + configurable via CSS. + +``HTML1`` + Old, table-based HTML writer. + +``ReST`` + ReStructured Text output. Since ReStructured Text is a bit strict + in it's parser, user input from the IRC meeting will often mess up + the conversion, and thus this isn't recommended for true use until + better escape functions can be written. (There is no security + risk from this plugin, ReST is run in secure mode). + +``HTMLfromReST`` + This runs the ReStructured Text writer, and uses ``docutils`` to + convert it to HTML. This requires the ``docutils`` package of + Python to be installed. + + Other config variables ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ These variables are set either in ``meetingLocalConfig.py`` (in the ``Config`` class) or in the supybot registry. @@ -517,16 +629,7 @@ These variables are set either in ``meetingLocalConfig.py`` (in the Input and output character set encodings. ``writer_map`` - A python dictionary listing what output formats will be used to - write our final results to a file, along with extensions to use. - For example:: - - writer_map = { - '.log.html':writers.HTMLlog(), - '.html': writers.HTML(), - '.txt': writers.RST(), - #'.rst.html':writers.HTMLfromRST(), - } + See the description in the section above. ``cssFile_minutes`` and ``cssFile_log`` @@ -553,7 +656,7 @@ These variables are set either in ``meetingLocalConfig.py`` (in the Advanced configuration ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ This gives a few examples of things you can do via ``meetingLocalConfig.py``. Most people probably won't need these @@ -562,12 +665,22 @@ things, and they aren't thoroughly explained here. You can make a per-channel config:: class Config(object): - def init(self): - if self.M.channel == '#some-channel': + def init_hook(self): + if self.M.channel == '#some-channel': self.logFileDir = '/some/directory' else: self.logFileDir = '/some/other/directory' +Make a per-channel writer_map (note that you shouldn't change +writer_map in place):: + + import writers + class Config(object): + def init_hook(self): + if self.M.channel == '#some-channel': + self.writer_map = self.writer_map.copy() + self.writer_map['.mw'] = writers.MediaWiki + The display styles (in html writers) can be modified also, by using the starthtml and endhtml attributes (put this in @@ -578,9 +691,11 @@ meetingLocalConfig.py:: items.Agreed.endhtml = '' -Adding a new custom command via ``meetingLocalConfig.py``. This -likely won't make sense unless you examine the code a bit:: +Adding a new custom command via ``meetingLocalConfig.py``. (This +likely won't make sense unless you examine the code a bit and know +esoteric things about python method types):: + import types class Config(object): def init(self): def do_party(self, nick, time_, **kwargs): @@ -600,6 +715,61 @@ Make a command alias. Make ``#weagree`` an alias for ``#agreed``:: +Supybot admin commands +---------------------- + +These commands are for the bot owners to manage all meetings served by +their bot. The expected use of these commands is when the bot is on +many channels as a public service, and the bot owner sometimes needs +to be able to monitor and adjust the overall situation, even if she is +not the chair of a meeting. + +All of these are regular supybot commands (as opposed to the commands +above). That means that the supybot capability system applies, and +they can be given either in any channel, either by direct address +(``BotName: ...``) or with the bot prefix character +(e.g. ``@ ...``). If there are commands with the +same name in multiple plugins, you need to prefix the command with the +plugin name (for example, ``BotName: meetbot recent`` instead of +``BotName: recent``) + +These are restricted to anyone with the ``admin`` capability on the +bot. + +``listmeetings`` + List all meetings. + +``savemeetings`` + Saves all active meetings on all channels and all networks. + +``addchair `` + Forcibly adds this nick as a chair on the giver channel on the given + network, if a meeting is active there. + +``deletemeeting `` + Delete a meeting from the cache. If save is given, save the meeting + first. The default value of ``save`` is True. This is useful for + when MeetBot becomes broken and is unable to properly save a + meeting, rendering the ``#endmeeting`` command non-functional. + +``recent`` + Display the last ten or so started meetings, along with their + channels. This is useful if you are the bot admin and want to see + just who all is using your bot, for example to better communicate + with those channels. + +To connect to multiple IRC networks, use the supybot ``Network`` +plugin to manage them. First, load the ``Network`` plugin, then use +the ``connect`` command to connect to the other network. Finally, you +need to tell supybot to join channels on the new. To do +that, you can use ``network command join ``. +(Alternatively, you can /msg the bot through the other network, but +you'll have to register your nick to it on the other network in order +for it to accept commands from you.) + + + + Developers ========== -- cgit v0.9.1