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

View File

@ -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"]

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`: 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`

View File

@ -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/*

View File

@ -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.**

View File

@ -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