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):
--
To view, visit
https://gerrit.wikimedia.org/r/238039
To unsubscribe, visit
https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I3c5b6bff67786c08797a8fe6df34a43e62eb952d
Gerrit-PatchSet: 5
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Owner: Merlijn van Deen <valhallasw(a)arctus.nl>
Gerrit-Reviewer: John Vandenberg <jayvdb(a)gmail.com>
Gerrit-Reviewer: Ladsgroup <ladsgroup(a)gmail.com>
Gerrit-Reviewer: XZise <CommodoreFabianus(a)gmx.de>
Gerrit-Reviewer: jenkins-bot <>