Update docs & docbuilder
This commit is contained in:
parent
f4fda5f60d
commit
ab8c3978fb
|
@ -1,21 +1,25 @@
|
||||||
FROM ubuntu:trusty
|
FROM ubuntu:xenial
|
||||||
|
|
||||||
COPY start /start
|
|
||||||
|
|
||||||
RUN apt-get update ; \
|
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 ; \
|
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 ; \
|
RUN pip3 install pytz praw
|
||||||
|
|
||||||
|
RUN cd /tmp ; \
|
||||||
wget https://github.com/jgarzik/python-bitcoinrpc/archive/master.zip ; \
|
wget https://github.com/jgarzik/python-bitcoinrpc/archive/master.zip ; \
|
||||||
unzip master.zip ; \
|
unzip master.zip ; \
|
||||||
cd python-bitcoinrpc-master/ ; \
|
cd python-bitcoinrpc-master/ ; \
|
||||||
python3 setup.py install ; \
|
python3 setup.py install
|
||||||
cd /tmp ; \
|
|
||||||
|
RUN cd /tmp ; \
|
||||||
wget https://github.com/dpedu/MySQL-for-Python-3/archive/master.zip -O mysqldb.zip ; \
|
wget https://github.com/dpedu/MySQL-for-Python-3/archive/master.zip -O mysqldb.zip ; \
|
||||||
unzip mysqldb.zip ; \
|
unzip mysqldb.zip ; \
|
||||||
cd MySQL-for-Python-3-master/ ; \
|
cd MySQL-for-Python-3-master/ ; \
|
||||||
python3 setup.py install ; \
|
python3 setup.py install
|
||||||
chmod +x /start ; \
|
|
||||||
|
COPY start /start
|
||||||
|
|
||||||
|
RUN chmod +x /start ; \
|
||||||
mkdir /tmp/docs
|
mkdir /tmp/docs
|
||||||
|
|
||||||
CMD /start
|
ENTRYPOINT ["/start"]
|
||||||
|
|
|
@ -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`:
|
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`
|
||||||
|
|
|
@ -2,10 +2,11 @@
|
||||||
cd /tmp
|
cd /tmp
|
||||||
if [ ! -d "pyircbot" ] ; then
|
if [ ! -d "pyircbot" ] ; then
|
||||||
mkdir pyircbot
|
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
|
tar zxvf pyircbot.tgz -C pyircbot/ --strip-components=1
|
||||||
fi
|
fi
|
||||||
cd pyircbot/docs/
|
cd pyircbot/docs/
|
||||||
make html
|
make html
|
||||||
rm -rf /tmp/docs/*
|
rm -rf /tmp/docs/*
|
||||||
cp -r _build/html/* /tmp/docs/
|
cp -r _build/html/* /tmp/docs/
|
||||||
|
chown -R 1000:1000 /tmp/docs/*
|
||||||
|
|
|
@ -7,8 +7,8 @@ Modules consist of a single python file, named for the module. For example, Echo
|
||||||
Getting Started
|
Getting Started
|
||||||
===============
|
===============
|
||||||
|
|
||||||
All modules should inherit from the base class
|
All modules should inherit from the base class
|
||||||
:doc:`ModuleBase </api/modulebase>`, and should be named matching their python
|
:doc:`ModuleBase </api/modulebase>`, and should be named matching their python
|
||||||
file's name.
|
file's name.
|
||||||
|
|
||||||
.. code-block:: python
|
.. 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
|
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
|
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.
|
modules one after the other so a long delay slows bot startup.
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
@ -26,7 +26,8 @@ modules one after the other so a long delay slows bot startup.
|
||||||
def __init__(self, bot, moduleName):
|
def __init__(self, bot, moduleName):
|
||||||
ModuleBase.__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`:
|
calling :py:meth:`pyircbot.modulebase.ModuleBase.loadConfig`:
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
@ -35,7 +36,7 @@ calling :py:meth:`pyircbot.modulebase.ModuleBase.loadConfig`:
|
||||||
print(self.config)
|
print(self.config)
|
||||||
|
|
||||||
In ``__init__``, the module lists what hooks it wants to listen for. Hooks are
|
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
|
.. code-block:: python
|
||||||
|
|
||||||
|
@ -47,20 +48,20 @@ Then, a handler for this hook:
|
||||||
|
|
||||||
def echo(self, event):
|
def echo(self, event):
|
||||||
|
|
||||||
The handler is passed and IRCEvent object containing the data sent by the irc
|
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.
|
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``
|
``event.args`` is the list of arguments the IRC server sent. ``event.prefix``
|
||||||
is the sender, parsed. ``trailing`` is arbitrary data associated
|
is the sender, parsed. ``trailing`` is arbitrary data associated
|
||||||
with the event. In the case of PRIVMSG: args has one entry - the channel name
|
with the event. In the case of PRIVMSG: args has one entry - the channel name
|
||||||
or nick the message was in/from.
|
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
|
``event.prefix.username``, ``event.prefix.hostname``, and the original unparsed
|
||||||
prefix, ``event.prefix.str``.
|
prefix, ``event.prefix.str``.
|
||||||
|
|
||||||
Prefix may also be a ``ServerPrefix`` object, if the hook is for an IRC method
|
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
|
that interacts with the server directly, such as PING. It would have the
|
||||||
properties ``event.prefix.hostname`` and ``event.prefix.str``.
|
properties ``event.prefix.hostname`` and ``event.prefix.str``.
|
||||||
|
|
||||||
Since the module described above echos messages, let's do that:
|
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)
|
self.bot.act_PRIVMSG(event.args[0], event.trailing)
|
||||||
|
|
||||||
This sends a PRIVMSG to the originating channel or nick, with the same msg
|
This sends a PRIVMSG to the originating channel or nick, with the same msg
|
||||||
content that was received.
|
content that was received.
|
||||||
|
|
||||||
Beyond this, a module's class can import or do anything python can to deliver
|
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
|
responses. For modules that use threads or connect to external services, a
|
||||||
shutdown handler is needed to ensure a clean shutdown.
|
shutdown handler is needed to ensure a clean shutdown.
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
|
@ -90,17 +91,17 @@ EchoExample module
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
from pyircbot.modulebase import ModuleBase,ModuleHook
|
from pyircbot.modulebase import ModuleBase,ModuleHook
|
||||||
|
|
||||||
class EchoExample(ModuleBase):
|
class EchoExample(ModuleBase):
|
||||||
def __init__(self, bot, moduleName):
|
def __init__(self, bot, moduleName):
|
||||||
ModuleBase.__init__(self, bot, moduleName)
|
ModuleBase.__init__(self, bot, moduleName)
|
||||||
self.loadConfig()
|
self.loadConfig()
|
||||||
print(self.config)
|
print(self.config)
|
||||||
self.hooks=[ModuleHook("PRIVMSG", self.echo)]
|
self.hooks=[ModuleHook("PRIVMSG", self.echo)]
|
||||||
|
|
||||||
def echo(self, event):
|
def echo(self, event):
|
||||||
self.bot.act_PRIVMSG(event.args[0], event.trailing)
|
self.bot.act_PRIVMSG(event.args[0], event.trailing)
|
||||||
|
|
||||||
def ondisable(self):
|
def ondisable(self):
|
||||||
print("I'm getting unloaded!")
|
print("I'm getting unloaded!")
|
||||||
|
|
||||||
|
@ -114,12 +115,12 @@ In usage:
|
||||||
New Style Module Hooks
|
New Style Module Hooks
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
Instead of receiving the values of the IRC event a module is responding to in
|
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
|
3 separate arguments, hooks can receive them as one object. The hook system
|
||||||
will automatically determine which argument style to use.
|
will automatically determine which argument style to use.
|
||||||
|
|
||||||
The reason for this change is to eliminate some unnecessary code in modules.
|
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
|
Any module that looks at a user's nick or hostname may find itself doing
|
||||||
something like this in every hook:
|
something like this in every hook:
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
@ -128,7 +129,7 @@ something like this in every hook:
|
||||||
prefixObj = self.bot.decodePrefix(prefix)
|
prefixObj = self.bot.decodePrefix(prefix)
|
||||||
self.bot.act_PRIVMSG(args[0], "Hello, %s. You are connecting from %s" % (prefixObj.nick, prefixObj.hostname))
|
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:
|
event has the prefix already parsed:
|
||||||
|
|
||||||
.. code-block:: python
|
.. 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.getDataPath`
|
||||||
- :py:meth:`pyircbot.pyircbot.PyIRCBot.getmodulebyname`
|
- :py:meth:`pyircbot.pyircbot.PyIRCBot.getmodulebyname`
|
||||||
|
|
||||||
:doc:`GameBase </api/modules/gamebase>` is a good example of the basic code
|
: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
|
structure a IRC game could follow, designed so different channels would have
|
||||||
separate game instances.
|
separate game instances.
|
||||||
|
|
||||||
Inter-module Communication
|
Inter-module Communication
|
||||||
--------------------------
|
--------------------------
|
||||||
|
|
||||||
In the list above, :py:meth:`pyircbot.pyircbot.PyIRCBot.getmodulebyname` can be
|
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.
|
instance of the other module's class.
|
||||||
|
|
||||||
But what if you wanted a module to find another by type? For example, a module
|
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
|
a cache API to function could find this module - or another that's functionally
|
||||||
equivalent.
|
equivalent.
|
||||||
|
|
||||||
|
@ -173,14 +174,14 @@ Modules providing a service state so like:
|
||||||
ModuleBase.__init__(self, bot, moduleName)
|
ModuleBase.__init__(self, bot, moduleName)
|
||||||
self.services=["cache"]
|
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.getmodulesbyservice` or
|
||||||
:py:meth:`pyircbot.pyircbot.PyIRCBot.getBestModuleForService` and passing the
|
:py:meth:`pyircbot.pyircbot.PyIRCBot.getBestModuleForService` and passing the
|
||||||
name "cache". The first returns a list of all modules offering the "cache"
|
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
|
service, the second returns an arbitrary module returning cache if more that
|
||||||
one is found.
|
one is found.
|
||||||
|
|
||||||
**PyIRCBot does NOT automatically handle inter-module communication. Meaning,
|
**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
|
service. Modules using a service MUST BE unloaded before the service module
|
||||||
is unloaded.**
|
is unloaded.**
|
||||||
|
|
|
@ -2,10 +2,10 @@
|
||||||
Dependencies
|
Dependencies
|
||||||
************
|
************
|
||||||
|
|
||||||
PyIRCBot is designed to run on Python 3, and is usually tested with 3.4. Python
|
PyIRCBot is designed to run on Python 3.5+, and is usually tested with 3.5.
|
||||||
2.x is not supported.
|
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.
|
form, not all features and modules will be available.
|
||||||
|
|
||||||
The following non-core Python modules are needed, and easily available through
|
The following non-core Python modules are needed, and easily available through
|
||||||
|
@ -15,7 +15,7 @@ Pip for python 3:
|
||||||
- pytz
|
- pytz
|
||||||
- PyYAML (yaml)
|
- PyYAML (yaml)
|
||||||
- requests
|
- requests
|
||||||
|
|
||||||
The following modules aren't available on pip, and are sourced from various
|
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
|
places. They are NOT required but certain modules won't be available without
|
||||||
them.
|
them.
|
||||||
|
@ -24,8 +24,8 @@ them.
|
||||||
- **pymysql** - https://github.com/dpedu/MySQL-for-Python-3 (needs \
|
- **pymysql** - https://github.com/dpedu/MySQL-for-Python-3 (needs \
|
||||||
libmysqlclient-dev on your system)
|
libmysqlclient-dev on your system)
|
||||||
|
|
||||||
At time of writing there is a bug that will prevent the bitcoinrpc module from
|
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.
|
working with Python 3. When pull `#55`_ is merged, the bug will be fixed.
|
||||||
Until then, using my `fork`_ is recommended.
|
Until then, using my `fork`_ is recommended.
|
||||||
|
|
||||||
.. _#55: https://github.com/jgarzik/python-bitcoinrpc/pull/55
|
.. _#55: https://github.com/jgarzik/python-bitcoinrpc/pull/55
|
||||||
|
|
Loading…
Reference in New Issue