Choose the docs theme and add some basic setup documentation
This commit is contained in:
parent
f8cb6b7575
commit
41eb244d25
@ -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
4
docs/dev/_dev.rst
Normal file
@ -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.
|
||||
|
||||
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`
|
||||
|
4
docs/modules/_modules.rst
Normal file
4
docs/modules/_modules.rst
Normal file
@ -0,0 +1,4 @@
|
||||
Included Modules
|
||||
================
|
||||
|
||||
TODO: Document included modules
|
4
docs/rpc/_rpc.rst
Normal file
4
docs/rpc/_rpc.rst
Normal file
@ -0,0 +1,4 @@
|
||||
RPC Usage
|
||||
=========
|
||||
|
||||
TODO: How to use RPC
|
14
docs/setup/_setup.rst
Normal file
14
docs/setup/_setup.rst
Normal 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
|
13
docs/setup/dependancies.rst
Normal file
13
docs/setup/dependancies.rst
Normal 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.
|
94
docs/setup/initial_config.rst
Normal file
94
docs/setup/initial_config.rst
Normal 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
22
docs/setup/running.rst
Normal 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.
|
Loading…
Reference in New Issue
Block a user