More documentation updates

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() <earwigbot.managers.CommandManager.call>`, which
+  you shouldn't have to use); you can safely reload all commands with
+  :py:meth:`commands.load() <earwigbot.bot.Bot.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)
+  <earwigbot.managers.TaskManager.start>`. :py:meth:`tasks.load()
+  <earwigbot.managers.TaskManager.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) <earwigbot.irc.IRConnection.say>` (more on
+  communicating with IRC below).
 
 - :py:attr:`~earwigbot.bot.Bot.wiki`: interface with the
   :doc:`Wiki Toolset <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)
+  <bot.irc.IRCConnection.say>`, :py:meth:`reply(data, msg)
+  <bot.irc.IRCConnection.reply>` (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) <bot.irc.IRCConnection.action>`,
+  :py:meth:`notice(chan_or_user, msg) <bot.irc.IRCConnection.notice>`,
+  :py:meth:`join(chan) <bot.irc.IRCConnection.join>`, and
+  :py:meth:`part(chan) <bot.irc.IRCConnection.part>`.
 
 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)
+  <earwigbot.tasks.BaseTask.make_summary>` 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 <toolset>`.
+  :py:meth:`tasks.start(task_name, **kwargs)
+  <earwigbot.managers.TaskManager.start>`, usually). This is where the bulk of
+  the task's code goes. For interfacing with MediaWiki sites, read up on the
+  :doc:`Wiki Toolset <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

docs/index.rst

@@ -45,4 +45,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

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/

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

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) <bot.logger>`.
 
 - 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()
+       <earwigbot.commands.BaseCommand.load>` and
+       :py:meth:`bot.tasks.load() <earwigbot.tasks.BaseTask.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

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