jenkins-bot has submitted this change and it was merged.
Change subject: docs: clean up a set of errors ......................................................................
docs: clean up a set of errors
There are still a few issues remaining, most notably related to the deprecation wrappers (a deprecated class becomes a function, which confuses sphinx) and the magic that transforms script docstrings.
Bug: T112491 Change-Id: I3c5b6bff67786c08797a8fe6df34a43e62eb952d --- M docs/api_ref/pywikibot.families.rst M docs/index.rst M pywikibot/backports.py M pywikibot/bot.py M pywikibot/data/wikidataquery.py M pywikibot/flow.py M pywikibot/i18n.py M pywikibot/login.py M pywikibot/page.py M pywikibot/site.py 10 files changed, 64 insertions(+), 50 deletions(-)
Approvals: XZise: Looks good to me, approved jenkins-bot: Verified
diff --git a/docs/api_ref/pywikibot.families.rst b/docs/api_ref/pywikibot.families.rst index 58cacf4..fb96513 100644 --- a/docs/api_ref/pywikibot.families.rst +++ b/docs/api_ref/pywikibot.families.rst @@ -153,10 +153,10 @@ :undoc-members: :show-inheritance:
-pywikibot.families.wikimedia_family module ------------------------------------------- +pywikibot.families.wikimediachapter_family module +-------------------------------------------------
-.. automodule:: pywikibot.families.wikimedia_family +.. automodule:: pywikibot.families.wikimediachapter_family :members: :undoc-members: :show-inheritance: diff --git a/docs/index.rst b/docs/index.rst index 3c1b87d..81e7ad6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,6 +46,16 @@ getting_help api_ref/index
+For framework developers: +========================= + +.. toctree:: + :maxdepth: 2 + + api_ref/tests/index + scripts.maintenance + + Miscellaneous ============= .. toctree:: diff --git a/pywikibot/backports.py b/pywikibot/backports.py index fbebf8f..cb44b6e 100644 --- a/pywikibot/backports.py +++ b/pywikibot/backports.py @@ -3,8 +3,18 @@ This module contains backports to support older Python versions.
They contain the backported code originally developed for Python. It is -therefore distributed under the PSF license, as follows: +therefore distributed under the PSF license. +""" +# +# (C) Python Software Foundation, 2001-2014 +# (C) with modifications from Pywikibot team, 2015 +# +# Distributed under the terms of the PSF license. +#
+from __future__ import unicode_literals + +__license__ = """ PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 -------------------------------------------- 1. This LICENSE AGREEMENT is between the Python Software Foundation @@ -52,14 +62,6 @@ agrees to be bound by the terms and conditions of this License Agreement. """ -# -# (C) Python Software Foundation, 2001-2014 -# (C) with modifications from Pywikibot team, 2015 -# -# Distributed under the terms of the PSF license. -# -from __future__ import unicode_literals - import logging import warnings
diff --git a/pywikibot/bot.py b/pywikibot/bot.py index dae9760..99a0d0f 100644 --- a/pywikibot/bot.py +++ b/pywikibot/bot.py @@ -2091,16 +2091,16 @@ @param data: data to be saved, or None if the diff should be created automatically @kwarg summary: revision comment, passed to ItemPage.editEntity - @kwtype summary: str + @type summary: str @kwarg show_diff: show changes between oldtext and newtext (default: True) - @kwtype show_diff: bool + @type show_diff: bool @kwarg ignore_server_errors: if True, server errors will be reported and ignored (default: False) - @kwtype ignore_server_errors: bool + @type ignore_server_errors: bool @kwarg ignore_save_related_errors: if True, errors related to - page save will be reported and ignored (default: False) - @kwtype ignore_save_related_errors: bool + page save will be reported and ignored (default: False) + @type ignore_save_related_errors: bool """ self.current_page = item
diff --git a/pywikibot/data/wikidataquery.py b/pywikibot/data/wikidataquery.py index 59cb48a..054eb44 100644 --- a/pywikibot/data/wikidataquery.py +++ b/pywikibot/data/wikidataquery.py @@ -232,7 +232,7 @@
Sub-classes must override this method.
- @raise NotImplementedError: Always raised by this abstract method + @raises NotImplementedError: Always raised by this abstract method """ raise NotImplementedError
diff --git a/pywikibot/flow.py b/pywikibot/flow.py index 27c59ce..46dfac9 100644 --- a/pywikibot/flow.py +++ b/pywikibot/flow.py @@ -46,8 +46,8 @@ @param title: normalized title of the page @type title: unicode
- @raise TypeError: incorrect use of parameters - @raise ValueError: use of non-Flow-enabled Site + @raises TypeError: incorrect use of parameters + @raises ValueError: use of non-Flow-enabled Site """ super(FlowPage, self).__init__(source, title)
@@ -194,8 +194,8 @@ @type topiclist_data: dict @return: A Topic object derived from the supplied data @rtype: Topic - @raise TypeError: any passed parameters have wrong types - @raise ValueError: the passed topiclist_data is missing required data + @raises TypeError: any passed parameters have wrong types + @raises ValueError: the passed topiclist_data is missing required data """ if not isinstance(board, Board): raise TypeError('board must be a pywikibot.flow.Board object.') @@ -276,7 +276,7 @@ @param uuid: UUID of a Flow post @type uuid: unicode
- @raise TypeError: incorrect types of parameters + @raises TypeError: incorrect types of parameters """ if not isinstance(page, Topic): raise TypeError('Page must be a Topic object') @@ -303,8 +303,8 @@ @type data: dict
@return: A Post object - @raise TypeError: data is not a dict - @raise ValueError: data is missing required entries + @raises TypeError: data is not a dict + @raises ValueError: data is missing required entries """ post = cls(page, post_uuid) post._set_data(data) @@ -316,8 +316,8 @@
@param data: The data to store internally @type data: dict - @raise TypeError: data is not a dict - @raise ValueError: missing data entries or post/revision not found + @raises TypeError: data is not a dict + @raises ValueError: missing data entries or post/revision not found """ if not isinstance(data, dict): raise TypeError('Illegal post data (must be a dictionary).') @@ -386,7 +386,7 @@ @type format: unicode @return: The contents of the post in the given content format @rtype: unicode - @raise NotImplementedError: use of 'sysop' + @raises NotImplementedError: use of 'sysop' """ if sysop: raise NotImplementedError @@ -402,7 +402,7 @@ @type format: str ('wikitext', 'html', or 'fixed-html') @param force: Whether to reload from the API instead of using the cache @type force: bool - @return This post's replies + @return: This post's replies @rtype: list of Posts """ if format not in ('wikitext', 'html', 'fixed-html'): diff --git a/pywikibot/i18n.py b/pywikibot/i18n.py index 661c015..c8c516c 100644 --- a/pywikibot/i18n.py +++ b/pywikibot/i18n.py @@ -529,13 +529,13 @@
As an examples, if we had several json dictionaries in test folder like:
- en.json: + en.json::
{ "test-plural": "Bot: Changing %(num)s {{PLURAL:%(num)d|page|pages}}.", }
- fr.json: + fr.json::
{ "test-plural": "Robot: Changer %(descr)s {{PLURAL:num|une page|quelques pages}}.", diff --git a/pywikibot/login.py b/pywikibot/login.py index ac37803..de84d9e 100644 --- a/pywikibot/login.py +++ b/pywikibot/login.py @@ -333,7 +333,7 @@ @type sysop: bool
@raises NoUsername: No username is configured for the requested site. - @raise OAuthImpossible: mwoauth isn't installed + @raises OAuthImpossible: mwoauth isn't installed """ if isinstance(mwoauth, ImportError): raise OAuthImpossible('mwoauth is not installed: %s.' % mwoauth) diff --git a/pywikibot/page.py b/pywikibot/page.py index 9bb1798..180ad39 100644 --- a/pywikibot/page.py +++ b/pywikibot/page.py @@ -3,6 +3,7 @@ Objects representing various types of MediaWiki, including Wikibase, pages.
This module also includes objects: + * Property: a type of semantic data. * Claim: an instance of a semantic assertion. * Revision: a single change to a wiki page. @@ -2024,8 +2025,8 @@ """Iterate templates used on this Page.
@return: a generator that yields a tuple for each use of a template - in the page, with the template Page as the first entry and a list of - parameters as the second entry. + in the page, with the template Page as the first entry and a list of + parameters as the second entry. """ # WARNING: may not return all templates used in particularly # intricate cases such as template substitution @@ -2270,7 +2271,7 @@ def getFileVersionHistory(self): """Return the file's version history.
- @return: A list of dictionaries with the following keys:: + @return: A list of dictionaries with the following keys:
[comment, sha1, url, timestamp, metadata, height, width, mime, user, descriptionurl, size] @@ -3092,10 +3093,10 @@ @kwarg entity_type: Wikibase entity type @type entity_type: str ('item' or 'property')
- @raise TypeError: incorrect use of parameters - @raise ValueError: incorrect namespace - @raise pywikibot.Error: title parsing problems - @raise NotImplementedError: the entity type is not supported + @raises TypeError: incorrect use of parameters + @raises ValueError: incorrect namespace + @raises pywikibot.Error: title parsing problems + @raises NotImplementedError: the entity type is not supported """ if not isinstance(site, pywikibot.site.DataSite): raise TypeError("site must be a pywikibot.site.DataSite object") @@ -3894,6 +3895,7 @@ Make the item redirect to another item.
You need to define an extra argument to make this work, like save=True + @param target_page: target of the redirect, this argument is required. @type target_page: pywikibot.Item or string @param force: if true, it sets the redirect target even the page diff --git a/pywikibot/site.py b/pywikibot/site.py index 7ba0b6b..a82da93 100644 --- a/pywikibot/site.py +++ b/pywikibot/site.py @@ -926,9 +926,9 @@ """ Return the site for a corresponding interwiki prefix.
- @raise SiteDefinitionError: if the url given in the interwiki table + @raises SiteDefinitionError: if the url given in the interwiki table doesn't match any of the existing families. - @raise KeyError: if the prefix is not an interwiki prefix. + @raises KeyError: if the prefix is not an interwiki prefix. """ return self._interwikimap[prefix].site
@@ -944,7 +944,7 @@ @type site: L{BaseSite} @return: The interwiki prefixes @rtype: list (guaranteed to be not empty) - @raise KeyError: if there is no interwiki prefix for that site. + @raises KeyError: if there is no interwiki prefix for that site. """ assert site is not None, 'Site must not be None' prefixes = set() @@ -963,9 +963,9 @@ link. So if that link also contains an interwiki link it does follow it as long as it's a local link.
- @raise SiteDefinitionError: if the url given in the interwiki table + @raises SiteDefinitionError: if the url given in the interwiki table doesn't match any of the existing families. - @raise KeyError: if the prefix is not an interwiki prefix. + @raises KeyError: if the prefix is not an interwiki prefix. """ return self._interwikimap[prefix].local
@@ -1569,7 +1569,7 @@ @type expiry: int/float (days), L{datetime.timedelta}, False (never) @return: The gathered property @rtype: various - @raise KeyError: If the key is not a valid siteinfo property and the + @raises KeyError: If the key is not a valid siteinfo property and the get_default option is set to False. @see: L{_get_siteinfo} """ @@ -2012,7 +2012,7 @@
Also logs out of the global account if linked to the user.
- @raise APIError: Logout is not available when OAuth enabled. + @raises APIError: Logout is not available when OAuth enabled. """ if self.is_oauth_token_available(): pywikibot.warning('Using OAuth suppresses logout function') @@ -2899,10 +2899,10 @@ @return: redirect target of page @rtype: BasePage
- @raise IsNotRedirectPage: page is not a redirect - @raise RuntimeError: no redirects found - @raise CircularRedirect: page is a circular redirect - @raise InterwikiRedirectPage: the redirect target is + @raises IsNotRedirectPage: page is not a redirect + @raises RuntimeError: no redirects found + @raises CircularRedirect: page is a circular redirect + @raises InterwikiRedirectPage: the redirect target is on another site """ if not self.page_isredirect(page):