Docstring cleanup for more modules

docs/api/earwigbot.wiki.rst

@@ -7,7 +7,6 @@ wiki Package
 .. automodule:: earwigbot.wiki
     :members:
     :undoc-members:
-    :show-inheritance:
 
 :mod:`category` Module
 ----------------------
@@ -15,7 +14,6 @@ wiki Package
 .. automodule:: earwigbot.wiki.category
     :members:
     :undoc-members:
-    :show-inheritance:
 
 :mod:`constants` Module
 -----------------------
@@ -23,7 +21,6 @@ wiki Package
 .. automodule:: earwigbot.wiki.constants
     :members:
     :undoc-members:
-    :show-inheritance:
 
 :mod:`copyright` Module
 -----------------------
@@ -31,7 +28,6 @@ wiki Package
 .. automodule:: earwigbot.wiki.copyright
     :members:
     :undoc-members:
-    :show-inheritance:
 
 :mod:`page` Module
 ------------------
@@ -47,7 +43,6 @@ wiki Package
 .. automodule:: earwigbot.wiki.site
     :members:
     :undoc-members:
-    :show-inheritance:
 
 :mod:`sitesdb` Module
 ---------------------
@@ -55,7 +50,6 @@ wiki Package
 .. automodule:: earwigbot.wiki.sitesdb
     :members:
     :undoc-members:
-    :show-inheritance:
 
 :mod:`user` Module
 ------------------
@@ -63,5 +57,3 @@ wiki Package
 .. automodule:: earwigbot.wiki.user
     :members:
     :undoc-members:
-    :show-inheritance:
-

earwigbot/wiki/__init__.py

@@ -21,18 +21,26 @@
 # SOFTWARE.
 
 """
-EarwigBot's Wiki Toolset
+**EarwigBot's Wiki Toolset**
 
 This is a collection of classes and functions to read from and write to
-Wikipedia and other wiki sites. No connection whatsoever to python-wikitools
-written by Mr.Z-man, other than a similar purpose. We share no code.
+Wikipedia and other wiki sites. No connection whatsoever to `python-wikitools
+<http://code.google.com/p/python-wikitools/>`_ written by `Mr.Z-man
+<http://en.wikipedia.org/wiki/User:Mr.Z-man>`_, other than a similar purpose.
+We share no code.
 
-Import the toolset directly with `from earwigbot import wiki`. If using the
-built-in integration with the rest of the bot, Bot() objects contain a `wiki`
-attribute, which is a SitesDB object tied to the sites.db file located in the
-same directory as config.yml. That object has the principal methods get_site,
-add_site, and remove_site that should handle all of your Site (and thus, Page,
-Category, and User) needs.
+Import the toolset directly with ``from earwigbot import wiki``. If using the
+built-in integration with the rest of the bot, :py:class:`~earwigbot.bot.Bot`
+objects contain a :py:attr:`~earwigbot.bot.Bot.wiki` attribute, which is a
+:py:class:`~earwigbot.wiki.sitesdb.SitesDB` object tied to the :file:`sites.db`
+file located in the same directory as :file:`config.yml`. That object has the
+principal methods :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.get_site`,
+:py:meth:`~earwigbot.wiki.sitesdb.SitesDB.add_site`, and
+:py:meth:`~earwigbot.wiki.sitesdb.SitesDB.remove_site` that should handle all
+of your :py:class:`~earwigbot.wiki.site.Site` (and thus,
+:py:class:`~earwigbot.wiki.page.Page`,
+:py:class:`~earwigbot.wiki.category.Category`, and
+:py:class:`~earwigbot.wiki.user.User`) needs.
 """
 
 from earwigbot.wiki.category import *

earwigbot/wiki/category.py

@@ -26,16 +26,20 @@ __all__ = ["Category"]
 
 class Category(Page):
     """
-    EarwigBot's Wiki Toolset: Category Class
+    **EarwigBot's Wiki Toolset: Category Class**
 
-    Represents a Category on a given Site, a subclass of Page. Provides
-    additional methods, but Page's own methods should work fine on Category
-    objects. Site.get_page() will return a Category instead of a Page if the
-    given title is in the category namespace; get_category() is shorthand,
-    because it accepts category names without the namespace prefix.
+    Represents a category on a given :py:class:`~earwigbot.wiki.site.Site`, a
+    subclass of :py:class:`~earwigbot.wiki.page.Page`. Provides additional
+    methods, but :py:class:`~earwigbot.wiki.page.Page`'s own methods should
+    work fine on :py:class:`Category` objects. :py:meth:`site.get_page()
+    <earwigbot.wiki.site.Site.get_page>` will return a :py:class:`Category`
+    instead of a :py:class:`~earwigbot.wiki.page.Page` if the given title is in
+    the category namespace; :py:meth:`~earwigbot.wiki.site.Site.get_category`
+    is shorthand, accepting category names without the namespace prefix.
 
-    Public methods:
-    get_members -- returns a list of page titles in the category
+    *Public methods:*
+
+    - :py:meth:`get_members`: returns a list of page titles in the category
     """
 
     def __repr__(self):
@@ -85,14 +89,15 @@ class Category(Page):
     def get_members(self, use_sql=False, limit=None):
         """Returns a list of page titles in the category.
 
-        If `use_sql` is True, we will use a SQL query instead of the API. Pages
-        will be returned as tuples of (title, pageid) instead of just titles.
+        If *use_sql* is ``True``, we will use a SQL query instead of the API.
+        Pages will be returned as tuples of ``(title, pageid)`` instead of just
+        titles.
 
-        If `limit` is provided, we will provide this many titles, or less if
-        the category is smaller. `limit` defaults to 50 for API queries; normal
+        If *limit* is provided, we will provide this many titles, or less if
+        the category is smaller. It defaults to 50 for API queries; normal
         users can go up to 500, and bots can go up to 5,000 on a single API
-        query. If we're using SQL, the limit is None by default (returning all
-        pages in the category), but an arbitrary limit can still be chosen.
+        query. If we're using SQL, the limit is ``None`` by default (returning
+        all pages in the category), but an arbitrary limit can still be chosen.
         """
         if use_sql:
             return self._get_members_via_sql(limit)

earwigbot/wiki/constants.py

@@ -21,15 +21,16 @@
 # SOFTWARE.
 
 """
-EarwigBot's Wiki Toolset: Constants
+**EarwigBot's Wiki Toolset: Constants**
 
 This module defines some useful constants:
-* USER_AGENT  - our default User Agent when making API queries
-* NS_*        - default namespace IDs for easy lookup
 
-Import directly with `from earwigbot.wiki import constants` or
-`from earwigbot.wiki.constants import *`. These are also available from
-earwigbot.wiki (e.g. `earwigbot.wiki.USER_AGENT`).
+- :py:const:`USER_AGENT`: our default User Agent when making API queries
+- :py:const:`NS_*`:       default namespace IDs for easy lookup
+
+Import directly with ``from earwigbot.wiki import constants`` or
+``from earwigbot.wiki.constants import *``. These are also available from
+:py:mod:`earwigbot.wiki` directly (e.g. ``earwigbot.wiki.USER_AGENT``).
 """
 
 # Default User Agent when making API queries:

earwigbot/wiki/site.py

@@ -50,11 +50,18 @@ class Site(object):
     """
     **EarwigBot's Wiki Toolset: Site Class**
 
-    Represents a Site, with support for API queries and returning Pages, Users,
-    and Categories. The constructor takes a bunch of arguments and you probably
-    won't need to call it directly, rather tools.get_site() for returning Site
-    instances, tools.add_site() for adding new ones to config, and
-    tools.del_site() for removing old ones from config, should suffice.
+    Represents a site, with support for API queries and returning
+    :py:class:`~earwigbot.wiki.page.Page`,
+    :py:class:`~earwigbot.wiki.user.User`,
+    and :py:class:`~earwigbot.wiki.category.Category` objects. The constructor
+    takes a bunch of arguments and you probably won't need to call it directly,
+    rather :py:meth:`wiki.get_site() <earwigbot.wiki.sitesdb.SitesDB.get_site>`
+    for returning :py:class:`Site`
+    instances, :py:meth:`wiki.add_site()
+    <earwigbot.wiki.sitesdb.SitesDB.add_site>` for adding new ones to our
+    database, and :py:meth:`wiki.remove_site()
+    <earwigbot.wiki.sitesdb.SitesDB.remove_site>` for removing old ones from
+    our database, should suffice.
 
     *Attributes:*