Choose the docs theme and add some basic setup documentation

dave 8 years ago
parent f8cb6b7575
commit 41eb244d25
  1. 2
  2. 4
  3. 17
  4. 4
  5. 4
  6. 14
  7. 13
  8. 94
  9. 22

@ -105,7 +105,7 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
html_theme = 'nature'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the

@ -0,0 +1,4 @@
Module Developer's Guide
TODO: Developing modules

@ -6,15 +6,22 @@
Welcome to pyircbot3's documentation!
PyIRCBot is a fault tolerant, multi-threaded, modular IRC bot designed for
Python 3.
.. toctree::
:maxdepth: 2
.. automodule:: core.pyircbot
:maxdepth: 8
Indices and tables
More Information
* :ref:`genindex`
* :ref:`modindex`

@ -0,0 +1,4 @@
Included Modules
TODO: Document included modules

@ -0,0 +1,4 @@
RPC Usage
TODO: How to use RPC

@ -0,0 +1,14 @@
Setup Tutorial
Installing and runnig PyIRCBot requires installing the needed dependancies and
providing some environmental information about where the bot is being run.
.. toctree::
:maxdepth: 8

@ -0,0 +1,13 @@
PyIRCBot is designed to run on Python 2.6+ and 3+ with zero code changes. Several
modules are needed that are available for both version of python.
The following non-core Python modules are needed:
- Yaml
.. note:: This list is incomplete.

@ -0,0 +1,94 @@
Initial Configuration
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.
Configuration is stored in 3 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 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 Configuration
.. code-block:: yaml
datadir: /home/example/bot/data/
rpcport: 1876
ipv6: off
port: 6667
- PingResponder
- Services
- AttributeStorage
The example bot instance is stored in `config.instance.yml`. 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.
.. cmdoption:: bot.rpcbind
Address on which to listen for RPC conncetions. RPC has no authentication so
using is reccommended.
.. cmdoption:: bot.rpcport
Port on which RPC will listen
.. cmdoption:: connection.server
Hostname or IP of the IRC server to connection to
.. cmdoption:: connection.ipv6
Enable or disable defaulting to IPv6 using the value "off" or "on"
.. cmdoption:: connection.port
Port to connect to on the IRC server
.. cmdoption:: modules
A YAML list of modules to load. Modules are loaded in the order they are listed here.

@ -0,0 +1,22 @@
Running a bot
The bot is invoked from the command line:
.. code-block:: sh
./pyircbot/ -c config.main.yml -b config.instance.yml
.. cmdoption:: -c --config
Path to the "core" config file
.. cmdoption:: -b --bot
Path to the "instance" config file
.. note:: A shell script,, is included in the source. This script
should be renamed and can be used to run the bot.
The bot will run and print all logging information to stdout.