diff --git a/docs/builder/Dockerfile b/docs/builder/Dockerfile index f7a9dfa..b9aef8a 100644 --- a/docs/builder/Dockerfile +++ b/docs/builder/Dockerfile @@ -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"] diff --git a/docs/builder/README.md b/docs/builder/README.md index 6001840..d5b079a 100644 --- a/docs/builder/README.md +++ b/docs/builder/README.md @@ -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` diff --git a/docs/builder/start b/docs/builder/start index 247b10b..4027a48 100755 --- a/docs/builder/start +++ b/docs/builder/start @@ -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/* diff --git a/docs/module_guide/_module_guide.rst b/docs/module_guide/_module_guide.rst index 2773c19..1331801 100644 --- a/docs/module_guide/_module_guide.rst +++ b/docs/module_guide/_module_guide.rst @@ -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 `, and should be named matching their python +All modules should inherit from the base class +:doc:`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 ` is a good example of the basic code -structure a IRC game could follow, designed so different channels would have +:doc:`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.** diff --git a/docs/setup/dependencies.rst b/docs/setup/dependencies.rst index 8a626fa..2d6eb64 100644 --- a/docs/setup/dependencies.rst +++ b/docs/setup/dependencies.rst @@ -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