Update docs

docs/api/irccore.rst

@@ -0,0 +1,10 @@
+:mod:`IRCCore` --- IRC protocol client
+======================================
+
+A simple and generic class for interacting with the IRC protocol.
+
+.. automodule:: pyircbot.irccore
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

docs/api/modules/attributestorage.rst

@@ -15,6 +15,9 @@ Items are dicts. An item can have many keys. Each key points to one value.
                +--> [ key ] --> [ value ]
     
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.AttributeStorage
     :members:
     :undoc-members:

docs/api/modules/attributestoragelite.rst

@@ -0,0 +1,12 @@
+:mod:`AttributeStorageLite` --- Item key/value storage
+======================================================
+
+With a SQLite backend.
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.AttributeStorageLite
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/bitcoinprice.rst

@@ -0,0 +1,15 @@
+:mod:`BitcoinPrice` --- Fetch the current Bitcoin price
+=======================================================
+
+Commands
+--------
+
+ - *.btc*, *.bitcoin* - fetch the bitcoin price
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.BitcoinPrice
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/calc.rst

@@ -0,0 +1,18 @@
+:mod:`Calc` --- IRC fact game
+=============================
+
+Commands
+--------
+
+ - *calc* - returns a random fact
+ - *calc something = some definition* - add a fact
+ - *calc something =* - delete a fact
+ - *match keyword* - search facts
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.Calc
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/cryptowallet.rst

@@ -3,6 +3,9 @@
 
 Module to provide a multi-type cryptocurrency wallet
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.CryptoWallet
     :members:
     :undoc-members:

docs/api/modules/cryptowalletrpc.rst

@@ -3,6 +3,9 @@
 
 Module capable of operating Bitcoind-style RPC. Provided as a service.
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.CryptoWalletRPC
     :members:
     :undoc-members:

docs/api/modules/dogedice.rst

@@ -3,6 +3,9 @@
 
 Module to provide a game for gambling Dogecoin
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.DogeDice
     :members:
     :undoc-members:

docs/api/modules/dogerpc.rst

@@ -3,6 +3,9 @@
 
 This module provides a service for interacting with dogecoind.
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.DogeRPC
     :members:
     :undoc-members:

docs/api/modules/dogescramble.rst

@@ -4,6 +4,9 @@
 This module provides a word scrambling game that rewards winners with small
 amounts of Dogecoin
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.DogeScramble
     :members:
     :undoc-members:

docs/api/modules/dogewallet.rst

@@ -3,6 +3,9 @@
 
 This module provides a dogecoin wallet hosted on the IRC bot's server
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.DogeWallet
     :members:
     :undoc-members:

docs/api/modules/duckhunt.rst

@@ -3,6 +3,9 @@
 
 An animal hunting IRC game
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.DuckHunt
     :members:
     :undoc-members:

docs/api/modules/error.rst

@@ -1,7 +1,8 @@
 :mod:`Error` --- A module to cause an error
 ===========================================
 
-yabba blahblah blahblah
+Class Reference
+---------------
 
 .. automodule:: pyircbot.modules.Error
     :members:

docs/api/modules/gamebase.rst

@@ -3,6 +3,9 @@
 
 A codebase for making IRC games
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.GameBase
     :members:
     :undoc-members:

docs/api/modules/inventory.rst

@@ -0,0 +1,16 @@
+:mod:`Inventory` --- Allows the bot to carry items
+==================================================
+
+Commands
+--------
+
+ - *botnick: inventory* - print current inventory
+ - *botnick: have a x* - give the bot an item
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.Inventory
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/linktitler.rst

@@ -0,0 +1,10 @@
+:mod:`LinkTitler` --- Fetch page titles for URLs posted in chat
+===============================================================
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.LinkTitler
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/mysql.rst

@@ -3,6 +3,9 @@
 
 Module providing a mysql type service
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.MySQL
     :members:
     :undoc-members:

docs/api/modules/nfllive.rst

@@ -0,0 +1,10 @@
+:mod:`NFLLive` --- Fetch NFL scores & game times
+================================================
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.NFLLive
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/nickuser.rst

@@ -3,6 +3,9 @@
 
 A module providing a simple login/logout account service
 
+Class Reference
+---------------
+
 .. automodule:: pyircbot.modules.NickUser
     :members:
     :undoc-members:

docs/api/modules/pingresponder.rst

@@ -1,7 +1,11 @@
 :mod:`PingResponder` --- Service ping responder
 ===============================================
 
-Module to repsond to irc server PING requests
+Module to repsond to irc server PING requests. This module requires no
+configuration
+
+Class Reference
+---------------
 
 .. automodule:: pyircbot.modules.PingResponder
     :members:

docs/api/modules/randquote.rst

@@ -0,0 +1,15 @@
+:mod:`RandQuote` --- Remember and retrieve quotes
+=================================================
+
+Commands
+--------
+
+ - *.randomquote .randquote .rq* - fetch and say a random quote
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.RandQuote
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/remind.rst

@@ -0,0 +1,18 @@
+:mod:`Remind` --- Set reminders
+===============================
+
+Commands
+--------
+
+ - *.at <time>* - remind at a specific time.
+    Example: *.at 20:45EST Do your homework!*
+ - *.in <time>* - Remind after an amount of time.
+    Example: *.in 1week5d2h1m Go fuck yourself*
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.Remind
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/scramble.rst

@@ -1,7 +1,8 @@
 :mod:`Scramble` --- Module to provide a word scramble game
 ==========================================================
 
-yabba blahblah blahblah
+Class Reference
+---------------
 
 .. automodule:: pyircbot.modules.Scramble
     :members:

docs/api/modules/seen.rst

@@ -1,7 +1,13 @@
 :mod:`Seen` --- !seen <username>
 ================================
 
-Provides !seen <username>
+Commands
+--------
+
+ - *!seen <username>* - finds the last time <username> was online
+
+Class Reference
+---------------
 
 .. automodule:: pyircbot.modules.Seen
     :members:

docs/api/modules/services.rst

@@ -1,7 +1,118 @@
 :mod:`Services` --- Module to provide nick and channel services
 ===============================================================
 
-yabba blahblah blahblah
+Services enables the bot to:
+
+ - Set it's nick on startup, and fall back to other names if one nick is taken
+ - Identify with nickserv or similar
+ - Ghost users using it's nick
+ - Request invites & join private channels
+
+Config
+-----
+
+.. code-block:: json
+
+    {
+        "user":{
+            "nick":[
+                "pyircbot3",
+                "pyircbot3_",
+                "pyircbot3__"
+            ],
+            "password":"nickservpassword",
+            "username":"pyircbot3",
+            "hostname":"pyircbot3.domain.com",
+            "realname":"pyircbot3"
+        },
+        "ident":{
+            "enable":"no",
+            "to":"nickserv",
+            "command":"identify %(password)s",
+            "ghost":"no",
+            "ghost_to":"nickserv",
+            "ghost_cmd":"ghost %(nick)s %(password)s"
+        },
+        "channels":[
+            "#xmopx"
+        ],
+        "privatechannels":{
+            "to":"chanserv",
+            "command":"invite %(channel)s",
+            "list":[
+                "#aprivatechannel"
+            ]
+        }
+    }
+
+.. cmdoption:: user.nick
+
+    A list of nicks, the first being the preferred nick and the others being 
+    fallbacks if the primary nick is taken.
+
+.. cmdoption:: user.password
+
+    Nickserv password
+
+.. cmdoption:: user.username
+
+    IRC username
+
+.. cmdoption:: user.hostname
+
+    Host name for the USER command
+
+.. cmdoption:: user.realname
+
+    IRC real name
+
+.. cmdoption:: ident.enable
+
+    Yes/no if you want to identify with Nickserv or another nick-protection
+    entity
+
+.. cmdoption:: ident.to
+
+    Nick the identify command will be sent to
+
+.. cmdoption:: ident.command
+
+    String formatted command to be sent for identification. Available tokens:
+     - password 
+
+.. cmdoption:: ident.ghost
+
+    Yes/no if the bot should attempt to ghost anyone using it's nickname
+
+.. cmdoption:: ident.ghost_to
+
+    Nick the ghost command will be sent to
+
+.. cmdoption:: ident.ghostcmd
+
+    String formatted command to be sent for ghosting. Available tokens:
+     - nick
+     - password
+
+.. cmdoption:: channels
+
+    List of channels to join on startup
+
+.. cmdoption:: privatechannels.to
+
+    Nick to send the invite command to
+
+.. cmdoption:: privatechannels.command
+
+    String formatted command to be sent for invitations. Available tokens:
+     - channel
+
+.. cmdoption:: privatechannels.list
+
+    List of channels to request an invite to join on startup
+
+Class Reference
+---------------
 
 .. automodule:: pyircbot.modules.Services
     :members:

docs/api/modules/sqlite.rst

@@ -0,0 +1,12 @@
+:mod:`SQLite` --- SQLite service
+================================
+
+Module providing a sqlite type service
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.SQLite
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/tell.rst

@@ -0,0 +1,16 @@
+:mod:`Tell` --- Pass messages to a user when they're next seen
+==============================================================
+
+Commands
+--------
+
+ - *.tell <user> <message>* - When <user> is next seen online, they will be
+    a PM with <message>.
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.Tell
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/urban.rst

@@ -0,0 +1,15 @@
+:mod:`Urban` --- Fetch random facts from Urban Dictionary
+=========================================================
+
+Commands
+--------
+
+ - *.urban* - fetch a random fact from Urban Dictionary
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.Urban
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/weather.rst

@@ -0,0 +1,21 @@
+:mod:`Weather` --- Fetch weather data by ZIP code
+=================================================
+
+Commands
+--------
+
+ - *.weather <location>*, *.w <location>* - fetch weather for a locaiton. If no location is passed, the user's preferred location will be used.
+    Example: *.w 95051*
+ - *.setloc <location>* - set your preferred location
+    Example: *.setloc Rochester, NY*
+    *.setloc 14623*
+ - *.wunit <type>* - set your preference between fahrenheit or celsius.
+    Example: *.setloc F*
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.Weather
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/modules/youtube.rst

@@ -0,0 +1,16 @@
+:mod:`Youtube` --- Fetch information for Youtube links
+======================================================
+
+Commands
+--------
+
+ - *.youtube <query>*, *.yt <query>* - search youtube for keywords <query>
+    Example: *.yt cute cats*
+
+Class Reference
+---------------
+
+.. automodule:: pyircbot.modules.Youtube
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/pyircbot.rst

@@ -1,7 +1,7 @@
 :mod:`PyIRCBot` --- Main class of the bot
 =========================================
 
-yabba blahblah blahblah
+Main bot class
 
 .. automodule:: pyircbot.pyircbot
     :members:

docs/builder/Dockerfile

@@ -2,8 +2,8 @@ FROM ubuntu:trusty
 
 COPY start /start
 
-RUN apt-get update ; apt-get install -y python3 python3-dev python3-pip python3-yaml make wget python3-sphinx python3-setuptools unzip libmysqlclient-dev ; 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 ; 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 ; mkdir /tmp/docs
+RUN apt-get update ; apt-get install -y python3 python3-sphinx python3-setuptools python3-dev python3-requests python3-pip python3-yaml make wget unzip libmysqlclient-dev ; 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 ; 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 ; mkdir /tmp/docs
 
 VOLUME /tmp/docs
 
-CMD ["/start"]
+CMD /start

docs/modules/_modules.rst

@@ -6,7 +6,7 @@ PyIRCBot includes several modules to add basic functionality to your bot.
 Contents:
 
 .. toctree::
-   :maxdepth: 8
+   :maxdepth: 1
    :glob:
    
    ../api/modules/*

docs/setup/dependancies.rst

@@ -2,8 +2,11 @@
 Dependancies
 ************
 
-PyIRCBot is designed to run on Python 3, and is usually tested with 3.4. Several
-modules are needed that are available for both version of python.
+PyIRCBot is designed to run on Python 3, and is usually tested with 3.4. Python
+2.x is not supported.
+
+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
 Pip for python 3:

docs/setup/initial_config.rst

@@ -7,71 +7,54 @@ This is a quick-start guide for the minimal setup to run PyIRCBot.
 Getting Started
 ===============
 
-PyIRCBot is modular. The core bot files may reside in one directory, modules in
-another, and userdata in a third. This way, setups can be created where many
-unprivileged users may rely one one set of core/module files they cannot edit,
-but can customize their instance.
+PyIRCBot is modular. The core bot files will reside whereever your system keeps
+python modules. User modules and data are kept where you want. This way, setups
+can be created where many unprivileged users may rely one one set of
+core/module files they cannot edit, but can customize their instance.
 
-Configuration is stored in 3 locations:
+Configuration is stored in 2 locations:
 
-- **Core config** - Environmental information for the bot, like where modules and 
-  core code is.
-- **Instance config** - Information about one instance of the bot, such as where
-  module data for the instance will be stored, server address, etc
-- **Module config** - Where module configuration files will be stored
-
-Core Configuration
-==================
-
-.. code-block:: python
-    
-    botdir: /home/example/bot/pyircbot/
-    moduledir: /home/example/bot/pyircbot/modules/
-
-The example core configuration is stored in `config.main.yml`. This contains two options:
-
-.. cmdoption:: botdir
-
-    Must be the absolute path to where main.py and the directory `core` resides.
-
-.. cmdoption:: moduledir
-
-    must be the absolute path to the directory of modules is.
-
-.. note:: All paths require a trailing slash
+- **Instance config** - Information about one instance of the bot, such as
+  where module data for the instance will be stored, server address, etc.
+- **Module config** - Where module configuration settings are be stored
 
 Instance Configuration
 ======================
 
-.. code-block:: yaml
+.. code-block:: json
 
-    bot:
-      datadir: /home/example/bot/data/
-      rpcbind: 0.0.0.0
-      rpcport: 1876
-    connection:
-      server: irc.freenode.net
-      ipv6: off
-      port: 6667
-    modules:
-      - PingResponder
-      - Services
-      - MySQL
-      - AttributeStorage
+    {
+        "bot":{
+            "datadir":"./data/",
+            "rpcbind":"0.0.0.0",
+            "rpcport":1876
+        },
+        "connection":{
+            "server":"irc.freenode.net",
+            "ipv6":"off",
+            "port":6667
+        },
+        "modules":[
+            "PingResponder",
+            "Services"
+        ]
+    }
 
-The example bot instance is stored in `config.instance.yml`. This contains several options:
+In the example directory, this is stored in `config.json`. This may be 
+substituted for a YML file with the same data structure. This contains several
+options:
 
 .. cmdoption:: bot.datadir
 
-    Location where module data will be stored. This directory generally contains
-    two folders: `config` and `data`. Config contains a yml file for each module
-    of the same name. Data can be empty, the bot will create directories for
-    each module as needed.
+    Location where module data will be stored. This directory generally
+    contains two folders: `config` and `data`. Config contains a config file
+    for each module of the same name. Data can be empty, the bot will create 
+    directories for each module as needed.
 
 .. cmdoption:: bot.rpcbind
 
-    Address on which to listen for RPC conncetions. RPC has no authentication so
-    using 127.0.0.1 is reccommended.
+    Address on which to listen for RPC conncetions. RPC has no authentication
+    so using 127.0.0.1 is reccommended.
 
 .. cmdoption:: bot.rpcport
 
@@ -91,4 +74,6 @@ The example bot instance is stored in `config.instance.yml`. This contains sever
 
 .. cmdoption:: modules
 
-    A YAML list of modules to load. Modules are loaded in the order they are listed here.
+    A list of modules to load. Modules are loaded in the order they are listed
+    here. :doc:`PingResponder </api/modules/pingresponder>` and :doc:`Services </api/modules/services>` are the *bare minimum* needed to open and
+    maintain and IRC connection.

docs/setup/running.rst

@@ -2,21 +2,20 @@
 Running a bot
 *************
 
+It is reccommended to install PyIRCBot3 with Pip or by running the install
+script included in the module folder. This installs the `pyircbot` command into
+ your $PATH, which is the easiest way to launch a bot. This document assumes it
+has been installed this way. 
+
+
 The bot is invoked from the command line:
 
 .. code-block:: sh
 
-    ./pyircbot/main.py -c config.main.yml -b config.instance.yml
+    pyircbot --config config.json
 
 .. cmdoption:: -c --config
 
-    Path to the "core" config file
-
-.. cmdoption:: -b --bot
-
-    Path to the "instance" config file
-
-.. note:: A shell script, run-example.sh, is included in the source. This script
-    should be renamed and can be used to run the bot.
+    Path to the bot's :doc:`config </setup/initial_config>` file
 
 The bot will run and print all logging information to stdout.

pyircbot/modules/PingResponder.py

@@ -14,6 +14,7 @@ class PingResponder(ModuleBase):
 		ModuleBase.__init__(self, bot, moduleName);
 		self.hooks=[ModuleHook("PING", self.pingrespond)]
 	def pingrespond(self, args, prefix, trailing):
+		"""Respond to the PING command"""
 		# got a ping? send it right back
 		self.bot.act_PONG(trailing)
 		self.log.info("%s Responded to a ping: %s" % (self.bot.get_nick(), trailing))

pyircbot/modules/Services.py

@@ -18,10 +18,12 @@ class Services(ModuleBase):
 		self.current_nick = 0
 		self.do_ghost = False
 	def doConnect(self, args, prefix, trailing):
+		"""Hook for when the IRC conneciton is opened"""
 		self.bot.act_NICK(self.config["user"]["nick"][0])
 		self.bot.act_USER(self.config["user"]["username"], self.config["user"]["hostname"], self.config["user"]["realname"])
 		
 	def nickTaken(self, args, prefix, trailing):
+		"""Hook that responds to 433, meaning our nick is taken"""
 		if self.config["ident"]["ghost"]:
 			self.do_ghost = True
 		self.current_nick+=1
@@ -31,6 +33,7 @@ class Services(ModuleBase):
 		self.bot.act_NICK(self.config["user"]["nick"][self.current_nick])
 
 	def initservices(self, args, prefix, trailing):
+		"""Hook that sets our initial nickname"""
 		if self.do_ghost:
 			self.bot.act_PRIVMSG(self.config["ident"]["ghost_to"], self.config["ident"]["ghost_cmd"] % {"nick":self.config["user"]["nick"][0], "password":self.config["user"]["password"]})
 			sleep(2)
@@ -38,11 +41,13 @@ class Services(ModuleBase):
 		self.do_initservices()
 	
 	def invited(self, args, prefix, trailing):
+		"""Hook responding to INVITE channel invitations"""
 		if trailing.lower() in self.config["privatechannels"]["list"]:
 			self.log.info("Invited to %s, joining" % trailing)
 			self.bot.act_JOIN(trailing)
 	
 	def do_initservices(self):
+		"""Identify with nickserv and join startup channels"""
 		" id to nickserv "
 		if self.config["ident"]["enable"]:
 			self.bot.act_PRIVMSG(self.config["ident"]["to"], self.config["ident"]["command"] % {"password":self.config["user"]["password"]})