Choose the docs theme and add some basic setup documentation

This commit is contained in:
dave 2014-10-02 13:51:42 -07:00
parent f8cb6b7575
commit 41eb244d25
9 changed files with 168 additions and 6 deletions

View File

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

4
docs/dev/_dev.rst Normal file
View File

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

View File

@ -6,15 +6,22 @@
Welcome to pyircbot3's documentation!
=====================================
PyIRCBot is a fault tolerant, multi-threaded, modular IRC bot designed for
Python 3.
Contents:
.. toctree::
:maxdepth: 2
:maxdepth: 8
setup/_setup.rst
modules/_modules.rst
rpc/_rpc.rst
dev/_dev.rst
#PyIRCBot.rst
.. automodule:: core.pyircbot
Indices and tables
==================
More Information
================
* :ref:`genindex`
* :ref:`modindex`

View File

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

4
docs/rpc/_rpc.rst Normal file
View File

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

14
docs/setup/_setup.rst Normal file
View File

@ -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.
Contents:
.. toctree::
:maxdepth: 8
dependancies.rst
initial_config.rst
running.rst

View File

@ -0,0 +1,13 @@
************
Dependancies
************
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.

View File

@ -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 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 Configuration
======================
.. code-block:: yaml
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
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 127.0.0.1 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.

22
docs/setup/running.rst Normal file
View File

@ -0,0 +1,22 @@
*************
Running a bot
*************
The bot is invoked from the command line:
.. code-block:: sh
./pyircbot/main.py -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, run-example.sh, 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.