From c51c83e94eebff460276b8c689bc8d422e7f7acd Mon Sep 17 00:00:00 2001 From: Ben Kurtovic Date: Sun, 29 Apr 2012 03:55:33 -0400 Subject: [PATCH] More documentation updates --- docs/customizing.rst | 41 +++++++++++++++++++++++------------------ docs/index.rst | 1 - docs/installation.rst | 35 ++++++++++++++++++----------------- docs/setup.rst | 2 +- docs/tips.rst | 51 ++++++++++++++++++++++++++++----------------------- docs/toolset.rst | 4 ++-- 6 files changed, 72 insertions(+), 62 deletions(-) diff --git a/docs/customizing.rst b/docs/customizing.rst index 04594dc..3d5bac6 100644 --- a/docs/customizing.rst +++ b/docs/customizing.rst @@ -26,14 +26,16 @@ The most useful attributes are: - :py:attr:`~earwigbot.bot.Bot.commands`: the bot's :py:class:`~earwigbot.managers.CommandManager`, which is used internally to - run IRC commands (through :py:meth:`bot.commands.call`, which you shouldn't - have to use); you can safely reload all commands with - :py:meth:`~earwigbot.bot.Bot.commands.load`. + run IRC commands (through + :py:meth:`commands.call() `, which + you shouldn't have to use); you can safely reload all commands with + :py:meth:`commands.load() `. - :py:attr:`~earwigbot.bot.Bot.tasks`: the bot's :py:class:`~earwigbot.managers.TaskManager`, which can be used to start tasks - with :py:attr:`~earwigbot.bot.Bot.tasks.start(task_name, **kwargs)`. - :py:meth:`~earwigbot.bot.Bot.tasks.load` can be used to safely reload all + with :py:meth:`tasks.start(task_name, **kwargs) + `. :py:meth:`tasks.load() + ` can be used to safely reload all tasks. - :py:attr:`~earwigbot.bot.Bot.frontend` / @@ -41,8 +43,8 @@ The most useful attributes are: :py:class:`earwigbot.irc.Frontend` and :py:class:`earwigbot.irc.Watcher`, respectively, which represent the bot's connections to these two servers; you can, for example, send a message to the frontend with - :py:attr:`~earwigbot.bot.Bot.frontend.say(chan, msg)` (more on communicating - with IRC below). + :py:meth:`frontend.say(chan, msg) ` (more on + communicating with IRC below). - :py:attr:`~earwigbot.bot.Bot.wiki`: interface with the :doc:`Wiki Toolset `. @@ -113,12 +115,14 @@ these are the basics: :py:class:`~earwigbot.commands.BaseCommand`'s :py:meth:`~earwigbot.commands.BaseCommand.__init__` method for the full list. - The most common ones are :py:attr:`self.say(chan_or_user, msg)`, - :py:attr:`self.reply(data, msg)` (convenience function; sends a reply to the + The most common ones are :py:meth:`say(chan_or_user, msg) + `, :py:meth:`reply(data, msg) + ` (convenience function; sends a reply to the issuer of the command in the channel it was received), - :py:attr:`self.action(chan_or_user, msg)`, - :py:attr:`self.notice(chan_or_user, msg)`, :py:attr:`self.join(chan)`, and - :py:attr:`self.part(chan)`. + :py:meth:`action(chan_or_user, msg) `, + :py:meth:`notice(chan_or_user, msg) `, + :py:meth:`join(chan) `, and + :py:meth:`part(chan) `. It's important to name the command class :py:class:`Command` within the file, or else the bot might not recognize it as a command. The name of the file @@ -149,9 +153,9 @@ are the basics: generated with :py:meth:`~earwigbot.tasks.BaseTask.make_summary`). For example, EarwigBot's :py:attr:`config.wiki["summary"]` is ``"([[WP:BOT|Bot]]; [[User:EarwigBot#Task $1|Task $1]]): $2"``, which the - task class's :py:attr:`~earwigbot.tasks.BaseTask.make_summary(comment)` - method will take and replace ``$1`` with the task number and ``$2`` with the - details of the edit. + task class's :py:meth:`make_summary(comment) + ` method will take and replace + ``$1`` with the task number and ``$2`` with the details of the edit. Additionally, :py:meth:`~earwigbot.tasks.BaseTask.shutoff_enabled` (which checks whether the bot has been told to stop on-wiki by checking the content @@ -175,9 +179,10 @@ are the basics: - Method :py:meth:`~earwigbot.tasks.BaseTask.run` is called with any number of keyword arguments every time the task is executed (by - :py:attr:`bot.tasks.start(task_name, **kwargs)`, usually). This is where the - bulk of the task's code goes. For interfacing with MediaWiki sites, read up - on the :doc:`Wiki Toolset `. + :py:meth:`tasks.start(task_name, **kwargs) + `, usually). This is where the bulk of + the task's code goes. For interfacing with MediaWiki sites, read up on the + :doc:`Wiki Toolset `. Tasks have access to :py:attr:`config.tasks[task_name]` for config information, which is a node in :file:`config.yml` like every other attribute of diff --git a/docs/index.rst b/docs/index.rst index c5aa2e9..987eca2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,4 +45,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/docs/installation.rst b/docs/installation.rst index 39996c9..857329d 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,23 +1,23 @@ Installation ============ -This package contains the core ``earwigbot``, abstracted enough that it should -be usable and customizable by anyone running a bot on a MediaWiki site. Since -it is component-based, the IRC components can be disabled if desired. IRC +This package contains the core :py:mod:`earwigbot`, abstracted enough that it +should be usable and customizable by anyone running a bot on a MediaWiki site. +Since it is component-based, the IRC components can be disabled if desired. IRC commands and bot tasks specific to `my instance of EarwigBot`_ that I don't feel the average user will need are available from the repository `earwigbot-plugins`_. -It's recommended to run the bot's unit tests before installing. Run ``python -setup.py test`` from the project's root directory. Note that some -tests require an internet connection, and others may take a while to run. +It's recommended to run the bot's unit tests before installing. Run +:command:`python setup.py test` from the project's root directory. Note that +some tests require an internet connection, and others may take a while to run. Coverage is currently rather incomplete. Latest release (v0.1) --------------------- EarwigBot is available from the `Python Package Index`_, so you can install the -latest release with ``pip install earwigbot`` (`get pip`_). +latest release with :command:`pip install earwigbot` (`get pip`_). You can also install it from source [1]_ directly:: @@ -31,11 +31,11 @@ You can also install it from source [1]_ directly:: Development version ------------------- -You can install the development version of the bot from ``git`` by using -setuptools/distribute's ``develop`` command [1]_, probably on the ``develop`` -branch which contains (usually) working code. ``master`` contains the latest -release. EarwigBot uses `git flow`_, so you're free to -browse by tags or by new features (``feature/*`` branches):: +You can install the development version of the bot from :command:`git` by using +setuptools/`distribute`_'s :command:`develop` command [1]_, probably on the +``develop`` branch which contains (usually) working code. ``master`` contains +the latest release. EarwigBot uses `git flow`_, so you're free to browse by +tags or by new features (``feature/*`` branches):: git clone git://github.com/earwig/earwigbot.git earwigbot cd earwigbot @@ -46,8 +46,9 @@ browse by tags or by new features (``feature/*`` branches):: .. [1] ``python setup.py install``/``develop`` may require root, or use the ``--user`` switch to install for the current user only. -.. _my instance of EarwigBot: http://en.wikipedia.org/wiki/User:EarwigBot -.. _earwigbot-plugins: https://github.com/earwig/earwigbot-plugins -.. _Python Package Index: http://pypi.python.org -.. _get pip: http://pypi.python.org/pypi/pip -.. _git flow: http://nvie.com/posts/a-successful-git-branching-model/ +.. _my instance of EarwigBot: http://en.wikipedia.org/wiki/User:EarwigBot +.. _earwigbot-plugins: https://github.com/earwig/earwigbot-plugins +.. _Python Package Index: http://pypi.python.org +.. _get pip: http://pypi.python.org/pypi/pip +.. _distribute: http://pypi.python.org/pypi/distribute +.. _git flow: http://nvie.com/posts/a-successful-git-branching-model/ diff --git a/docs/setup.rst b/docs/setup.rst index ea01b49..81523df 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -25,4 +25,4 @@ You can stop the bot at any time with :kbd:`Control-c`, same as you stop a normal Python program, and it will try to exit safely. You can also use the "``!quit``" command on IRC. -.. _explanation of YAML: http://en.wikipedia.org/wiki/YAML +.. _explanation of YAML: http://en.wikipedia.org/wiki/YAML diff --git a/docs/tips.rst b/docs/tips.rst index 7a4e34a..6836b7c 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -3,21 +3,24 @@ Tips - Logging_ is a fantastic way to monitor the bot's progress as it runs. It has a slew of built-in loggers, and enabling log retention (so logs are saved to - ``logs/`` in the working directory) is highly recommended. In the normal + :file:`logs/` in the working directory) is highly recommended. In the normal setup, there are three log files, each of which "rotate" at a specific time - (``filename.log`` becomes ``filename.log.2012-04-10``, for example). The - ``debug.log`` file rotates every hour, and maintains six hours of logs of - every level (``DEBUG`` and up). ``bot.log`` rotates every day at midnight, - and maintains seven days of non-debug logs (``INFO`` and up). Finally, - ``error.log`` rotates every Sunday night, and maintains four weeks of logs - indicating unexpected events (``WARNING`` and up). - - To use logging in your commands or tasks (recommended), ``BaseCommand`` and - ``BaseTask`` provide ``logger`` attributes configured for the specific - command or task. If you're working with other classes, ``bot.logger`` is the - root logger (``logging.getLogger("earwigbot")`` by default), so you can use - ``getChild`` to make your logger. For example, task loggers are essentially - ``bot.logger.getChild("tasks").getChild(task.name)``. + (:file:`filename.log` becomes :file:`filename.log.2012-04-10`, for example). + The :file:`debug.log` file rotates every hour, and maintains six hours of + logs of every level (``DEBUG`` and up). :file:`bot.log` rotates every day at + midnight, and maintains seven days of non-debug logs (``INFO`` and up). + Finally, :file:`error.log` rotates every Sunday night, and maintains four + weeks of logs indicating unexpected events (``WARNING`` and up). + + To use logging in your commands or tasks (recommended), + :py:class:~earwigbot.commands.BaseCommand` and + :py:class:~earwigbot.tasks.BaseTask` provide :py:attr:`logger` attributes + configured for the specific command or task. If you're working with other + classes, :py:attr:`bot.logger` is the root logger + (:py:obj:`logging.getLogger("earwigbot")` by default), so you can use + :py:func:`~logging.Logger.getChild` to make your logger. For example, task + loggers are essentially + :py:attr:`bot.logger.getChild("tasks").getChild(task.name) `. - A very useful IRC command is "``!reload``", which reloads all commands and tasks without restarting the bot. [1]_ Combined with using the `!git plugin`_ @@ -25,17 +28,19 @@ Tips development workflow if the bot runs on an external server and you set up its working directory as a git repo. -- You can run a task by itself instead of the entire bot with ``earwigbot - path/to/working/dir --task task_name``. +- You can run a task by itself instead of the entire bot with + :command:`earwigbot path/to/working/dir --task task_name`. -- Questions, comments, or suggestions about the documentation? `Let me know`_ - so I can improve it for other people. +- Questions, comments, or suggestions about the documentation? `Let me know`_, + or `create an issue`_ so I can improve it for other people. .. rubric:: Footnotes -.. [1] In reality, all this does is call ``bot.commands.load()`` and - ``bot.tasks.load()``! +.. [1] In reality, all this does is call :py:meth:`bot.commands.load() + ` and + :py:meth:`bot.tasks.load() `! -.. _logging: http://docs.python.org/library/logging.html -.. _Let me know: ben.kurtovic@verizon.net -.. _!git plugin: https://github.com/earwig/earwigbot-plugins/blob/develop/commands/git.py +.. _logging: http://docs.python.org/library/logging.html +.. _!git plugin: https://github.com/earwig/earwigbot-plugins/blob/develop/commands/git.py +.. _Let me know: ben.kurtovic@verizon.net +.. _create an issue: https://github.com/earwig/earwigbot/issues diff --git a/docs/toolset.rst b/docs/toolset.rst index 6b8a719..dba7700 100644 --- a/docs/toolset.rst +++ b/docs/toolset.rst @@ -166,5 +166,5 @@ docstrings`_ to learn how to use it in a more hands-on fashion. For reference, ``bot.wiki`` is an instance of ``earwigbot.wiki.SitesDB`` tied to the ``sites.db`` file in the bot's working directory. -.. _Pywikipedia framework: http://pywikipediabot.sourceforge.net/ -.. _its code and docstrings: https://github.com/earwig/earwigbot/tree/develop/earwigbot/wiki +.. _Pywikipedia framework: http://pywikipediabot.sourceforge.net/ +.. _its code and docstrings: https://github.com/earwig/earwigbot/tree/develop/earwigbot/wiki