dave
/
pyircbot
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update docs & docbuilder

This commit is contained in:
dave 2017-03-28 16:48:31 -07:00
parent f4fda5f60d
commit ab8c3978fb
5 changed files with 60 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/builder/Dockerfile
View File

@ -1,21 +1,25 @@
FROM ubuntu:trusty
COPY start /start
FROM ubuntu:xenial
RUN apt-get update ; \
apt-get install -y python3 python3-sphinx python3-setuptools python3-dev python3-requests python3-pip python3-lxml make wget unzip libmysqlclient-dev ; \
pip3 install pytz praw ; \
cd /tmp ; \
apt-get install -y python3 python3-sphinx python3-setuptools python3-dev python3-requests python3-pip python3-lxml make wget unzip libmysqlclient-dev
RUN pip3 install pytz praw
RUN cd /tmp ; \
wget https://github.com/jgarzik/python-bitcoinrpc/archive/master.zip ; \
unzip master.zip ; \
cd python-bitcoinrpc-master/ ; \
python3 setup.py install ; \
cd /tmp ; \
python3 setup.py install
RUN cd /tmp ; \
wget https://github.com/dpedu/MySQL-for-Python-3/archive/master.zip -O mysqldb.zip ; \
unzip mysqldb.zip ; \
cd MySQL-for-Python-3-master/ ; \
python3 setup.py install ; \
chmod +x /start ; \
python3 setup.py install
COPY start /start
RUN chmod +x /start ; \
mkdir /tmp/docs
CMD /start
ENTRYPOINT ["/start"]

3
docs/builder/README.md
View File

@ -10,4 +10,5 @@ A docker image for building pyircbot's docs.
Or, use a local directory instead of git master and build docs into `docs/_build/html`:
* `docker run -it --rm -v /localpath/to/pyircbot/repo/:/tmp/pyircbot pyircbotdocbuilder /start`
* `mkdir docs/_build`
* `docker run -it --rm -v /localpath/to/pyircbot/repo/:/tmp/pyircbot/ pybdocbuilder`

3
docs/builder/start
View File

@ -2,10 +2,11 @@
cd /tmp
if [ ! -d "pyircbot" ] ; then
mkdir pyircbot
wget http://gitlab.xmopx.net/dave/pyircbot3/repository/archive.tar.gz?ref=master -O pyircbot.tgz
wget http://gitlab.davepedu.com/dave/pyircbot3/repository/archive.tar.gz?ref=master -O pyircbot.tgz
tar zxvf pyircbot.tgz -C pyircbot/ --strip-components=1
fi
cd pyircbot/docs/
make html
rm -rf /tmp/docs/*
cp -r _build/html/* /tmp/docs/
chown -R 1000:1000 /tmp/docs/*

69
docs/module_guide/_module_guide.rst
View File

@ -7,8 +7,8 @@ Modules consist of a single python file, named for the module. For example, Echo
Getting Started
===============
All modules should inherit from the base class
:doc:`ModuleBase </api/modulebase>`, and should be named matching their python
All modules should inherit from the base class
:doc:`ModuleBase </api/modulebase>`, and should be named matching their python
file's name.
.. code-block:: python
@ -18,7 +18,7 @@ file's name.
The class's ``__init__`` method accepts 2 args - a reference to the bot's API
and what the bot has decided to name this module. These are passed to
ModuleBase. Module's init method should be as quick as possible. The bot loads
ModuleBase. Module's init method should be as quick as possible. The bot loads
modules one after the other so a long delay slows bot startup.
.. code-block:: python
@ -26,7 +26,8 @@ modules one after the other so a long delay slows bot startup.
def __init__(self, bot, moduleName):
ModuleBase.__init__(self, bot, moduleName)
If your module has a config file - EchoExample.json - it can be loaded by
If your module has a config file - EchoExample.json - it will be automatically
loaded on module startup. It can be manually reloaded by
calling :py:meth:`pyircbot.modulebase.ModuleBase.loadConfig`:
.. code-block:: python
@ -35,7 +36,7 @@ calling :py:meth:`pyircbot.modulebase.ModuleBase.loadConfig`:
print(self.config)
In ``__init__``, the module lists what hooks it wants to listen for. Hooks are
executed when the corresponding IRC protocol command is received.
executed when the corresponding IRC protocol command is received.
.. code-block:: python
@ -47,20 +48,20 @@ Then, a handler for this hook:
def echo(self, event):
The handler is passed and IRCEvent object containing the data sent by the irc
server. The values of these are can vary, but the format is alwaysthe same.
The handler is passed and IRCEvent object containing the data sent by the irc
server. The values of these are can vary, but the format is alwaysthe same.
``event.args`` is the list of arguments the IRC server sent. ``event.prefix``
is the sender, parsed. ``trailing`` is arbitrary data associated
with the event. In the case of PRIVMSG: args has one entry - the channel name
``event.args`` is the list of arguments the IRC server sent. ``event.prefix``
is the sender, parsed. ``trailing`` is arbitrary data associated
with the event. In the case of PRIVMSG: args has one entry - the channel name
or nick the message was in/from.
Prefix is an ``UserPrefix`` object with the properties ``event.prefix.nick``,
Prefix is an ``UserPrefix`` object with the properties ``event.prefix.nick``,
``event.prefix.username``, ``event.prefix.hostname``, and the original unparsed
prefix, ``event.prefix.str``.
Prefix may also be a ``ServerPrefix`` object, if the hook is for an IRC method
that interacts with the server directly, such as PING. It would have the
Prefix may also be a ``ServerPrefix`` object, if the hook is for an IRC method
that interacts with the server directly, such as PING. It would have the
properties ``event.prefix.hostname`` and ``event.prefix.str``.
Since the module described above echos messages, let's do that:
@ -69,12 +70,12 @@ Since the module described above echos messages, let's do that:
self.bot.act_PRIVMSG(event.args[0], event.trailing)
This sends a PRIVMSG to the originating channel or nick, with the same msg
content that was received.
This sends a PRIVMSG to the originating channel or nick, with the same msg
content that was received.
Beyond this, a module's class can import or do anything python can to deliver
responses. For modules that use threads or connect to external services, a
shutdown handler is needed to ensure a clean shutdown.
responses. For modules that use threads or connect to external services, a
shutdown handler is needed to ensure a clean shutdown.
.. code-block:: python
@ -90,17 +91,17 @@ EchoExample module
.. code-block:: python
from pyircbot.modulebase import ModuleBase,ModuleHook
class EchoExample(ModuleBase):
def __init__(self, bot, moduleName):
ModuleBase.__init__(self, bot, moduleName)
self.loadConfig()
print(self.config)
self.hooks=[ModuleHook("PRIVMSG", self.echo)]
def echo(self, event):
self.bot.act_PRIVMSG(event.args[0], event.trailing)
def ondisable(self):
print("I'm getting unloaded!")
@ -114,12 +115,12 @@ In usage:
New Style Module Hooks
----------------------
Instead of receiving the values of the IRC event a module is responding to in
3 separate arguments, hooks can receive them as one object. The hook system
Instead of receiving the values of the IRC event a module is responding to in
3 separate arguments, hooks can receive them as one object. The hook system
will automatically determine which argument style to use.
The reason for this change is to eliminate some unnecessary code in modules.
Any module that looks at a user's nick or hostname may find itself doing
The reason for this change is to eliminate some unnecessary code in modules.
Any module that looks at a user's nick or hostname may find itself doing
something like this in every hook:
.. code-block:: python
@ -128,7 +129,7 @@ something like this in every hook:
prefixObj = self.bot.decodePrefix(prefix)
self.bot.act_PRIVMSG(args[0], "Hello, %s. You are connecting from %s" % (prefixObj.nick, prefixObj.hostname))
With the new style, one line can be eliminated, as the passed ``IRCEvent``
With the new style, one line can be eliminated, as the passed ``IRCEvent``
event has the prefix already parsed:
.. code-block:: python
@ -149,19 +150,19 @@ Refer to existing modules for helper methods from elsewhere in PyIRCBot.
- :py:meth:`pyircbot.pyircbot.PyIRCBot.getDataPath`
- :py:meth:`pyircbot.pyircbot.PyIRCBot.getmodulebyname`
:doc:`GameBase </api/modules/gamebase>` is a good example of the basic code
structure a IRC game could follow, designed so different channels would have
:doc:`GameBase </api/modules/gamebase>` is a good example of the basic code
structure a IRC game could follow, designed so different channels would have
separate game instances.
Inter-module Communication
--------------------------
In the list above, :py:meth:`pyircbot.pyircbot.PyIRCBot.getmodulebyname` can be
used to retrieve a reference to another loaded module. This is simply the
used to retrieve a reference to another loaded module. This is simply the
instance of the other module's class.
But what if you wanted a module to find another by type? For example, a module
providing a cache API could provide a service called "cache". Modules that use
providing a cache API could provide a service called "cache". Modules that use
a cache API to function could find this module - or another that's functionally
equivalent.
@ -173,14 +174,14 @@ Modules providing a service state so like:
ModuleBase.__init__(self, bot, moduleName)
self.services=["cache"]
Then, another module can find this one by using either
Then, another module can find this one by using either
:py:meth:`pyircbot.pyircbot.PyIRCBot.getmodulesbyservice` or
:py:meth:`pyircbot.pyircbot.PyIRCBot.getBestModuleForService` and passing the
name "cache". The first returns a list of all modules offering the "cache"
service, the second returns an arbitrary module returning cache if more that
:py:meth:`pyircbot.pyircbot.PyIRCBot.getBestModuleForService` and passing the
name "cache". The first returns a list of all modules offering the "cache"
service, the second returns an arbitrary module returning cache if more that
one is found.
**PyIRCBot does NOT automatically handle inter-module communication. Meaning,
modules providing a service should be loaded before modules requiring the
modules providing a service should be loaded before modules requiring the
service. Modules using a service MUST BE unloaded before the service module
is unloaded.**

12
docs/setup/dependencies.rst
View File

@ -2,10 +2,10 @@
Dependencies
************
PyIRCBot is designed to run on Python 3, and is usually tested with 3.4. Python
2.x is not supported.
PyIRCBot is designed to run on Python 3.5+, and is usually tested with 3.5.
Python 2.x and older versions of 3.x are not supported.
Although **no** non-core modules are needed to run PyIRCBot in it's most basic
Although **no** non-core modules are needed to run PyIRCBot in it's most basic
form, not all features and modules will be available.
The following non-core Python modules are needed, and easily available through
@ -15,7 +15,7 @@ Pip for python 3:
- pytz
- PyYAML (yaml)
- requests
The following modules aren't available on pip, and are sourced from various
places. They are NOT required but certain modules won't be available without
them.
@ -24,8 +24,8 @@ them.
- **pymysql** - https://github.com/dpedu/MySQL-for-Python-3 (needs \
libmysqlclient-dev on your system)
At time of writing there is a bug that will prevent the bitcoinrpc module from
working with Python 3. When pull `#55`_ is merged, the bug will be fixed.
At time of writing there is a bug that will prevent the bitcoinrpc module from
working with Python 3. When pull `#55`_ is merged, the bug will be fixed.
Until then, using my `fork`_ is recommended.
.. _#55: https://github.com/jgarzik/python-bitcoinrpc/pull/55