From c22cc2dc5eb3efeaaec474daaca3fa917228e7c4 Mon Sep 17 00:00:00 2001 From: Ben Kurtovic Date: Sat, 5 May 2012 21:05:34 -0400 Subject: [PATCH] Docstring cleanup for more modules --- docs/api/earwigbot.wiki.rst | 8 -------- earwigbot/wiki/__init__.py | 26 +++++++++++++++++--------- earwigbot/wiki/category.py | 33 +++++++++++++++++++-------------- earwigbot/wiki/constants.py | 13 +++++++------ earwigbot/wiki/site.py | 17 ++++++++++++----- 5 files changed, 55 insertions(+), 42 deletions(-) diff --git a/docs/api/earwigbot.wiki.rst b/docs/api/earwigbot.wiki.rst index 9e7a5ad..806b3eb 100644 --- a/docs/api/earwigbot.wiki.rst +++ b/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: - diff --git a/earwigbot/wiki/__init__.py b/earwigbot/wiki/__init__.py index 9765239..16bf7e2 100644 --- a/earwigbot/wiki/__init__.py +++ b/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 +`_ written by `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 * diff --git a/earwigbot/wiki/category.py b/earwigbot/wiki/category.py index e0209b2..06fbcbd 100644 --- a/earwigbot/wiki/category.py +++ b/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() + ` 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) diff --git a/earwigbot/wiki/constants.py b/earwigbot/wiki/constants.py index 7ccb136..13a1efd 100644 --- a/earwigbot/wiki/constants.py +++ b/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: diff --git a/earwigbot/wiki/site.py b/earwigbot/wiki/site.py index 7b94946..dbdb824 100644 --- a/earwigbot/wiki/site.py +++ b/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() ` + for returning :py:class:`Site` + instances, :py:meth:`wiki.add_site() + ` for adding new ones to our + database, and :py:meth:`wiki.remove_site() + ` for removing old ones from + our database, should suffice. *Attributes:*