From 41eb244d259cbbd1f8f9ea218cdd02388ab59ae9 Mon Sep 17 00:00:00 2001 From: dave Date: Thu, 2 Oct 2014 13:51:42 -0700 Subject: [PATCH] Choose the docs theme and add some basic setup documentation --- docs/conf.py | 2 +- docs/dev/_dev.rst | 4 ++ docs/index.rst | 17 +++++-- docs/modules/_modules.rst | 4 ++ docs/rpc/_rpc.rst | 4 ++ docs/setup/_setup.rst | 14 ++++++ docs/setup/dependancies.rst | 13 +++++ docs/setup/initial_config.rst | 94 +++++++++++++++++++++++++++++++++++ docs/setup/running.rst | 22 ++++++++ 9 files changed, 168 insertions(+), 6 deletions(-) create mode 100644 docs/dev/_dev.rst create mode 100644 docs/modules/_modules.rst create mode 100644 docs/rpc/_rpc.rst create mode 100644 docs/setup/_setup.rst create mode 100644 docs/setup/dependancies.rst create mode 100644 docs/setup/initial_config.rst create mode 100644 docs/setup/running.rst diff --git a/docs/conf.py b/docs/conf.py index ec22625..17d70bf 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -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 diff --git a/docs/dev/_dev.rst b/docs/dev/_dev.rst new file mode 100644 index 0000000..657fc15 --- /dev/null +++ b/docs/dev/_dev.rst @@ -0,0 +1,4 @@ +Module Developer's Guide +======================== + +TODO: Developing modules \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 5ed59ee..3308643 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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` diff --git a/docs/modules/_modules.rst b/docs/modules/_modules.rst new file mode 100644 index 0000000..99ded63 --- /dev/null +++ b/docs/modules/_modules.rst @@ -0,0 +1,4 @@ +Included Modules +================ + +TODO: Document included modules \ No newline at end of file diff --git a/docs/rpc/_rpc.rst b/docs/rpc/_rpc.rst new file mode 100644 index 0000000..dd158fc --- /dev/null +++ b/docs/rpc/_rpc.rst @@ -0,0 +1,4 @@ +RPC Usage +========= + +TODO: How to use RPC \ No newline at end of file diff --git a/docs/setup/_setup.rst b/docs/setup/_setup.rst new file mode 100644 index 0000000..5907a3c --- /dev/null +++ b/docs/setup/_setup.rst @@ -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 diff --git a/docs/setup/dependancies.rst b/docs/setup/dependancies.rst new file mode 100644 index 0000000..40fe050 --- /dev/null +++ b/docs/setup/dependancies.rst @@ -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. \ No newline at end of file diff --git a/docs/setup/initial_config.rst b/docs/setup/initial_config.rst new file mode 100644 index 0000000..abedcba --- /dev/null +++ b/docs/setup/initial_config.rst @@ -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. \ No newline at end of file diff --git a/docs/setup/running.rst b/docs/setup/running.rst new file mode 100644 index 0000000..20ad221 --- /dev/null +++ b/docs/setup/running.rst @@ -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.