jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/731124 )

Change subject: [doc] use sphinx directives for versioning ......................................................................

[doc] use sphinx directives for versioning

Change-Id: I9d4d9484308f40664d5b01f88cc07e11ce1e2f38 --- M pywikibot/__init__.py M pywikibot/__metadata__.py M pywikibot/bot_choice.py M pywikibot/comms/eventstreams.py M pywikibot/config.py M pywikibot/exceptions.py M pywikibot/families/commons_family.py M pywikibot/families/foundation_family.py M pywikibot/families/lingualibre_family.py M pywikibot/families/wikihow_family.py M pywikibot/families/wikimania_family.py M pywikibot/families/wikispore_family.py M pywikibot/family.py M pywikibot/page/__init__.py M pywikibot/pagegenerators.py M pywikibot/plural.py M pywikibot/site/_apisite.py M pywikibot/site/_generators.py M pywikibot/site_detect.py M pywikibot/specialbots/_upload.py M pywikibot/textlib.py M pywikibot/userinterfaces/_interface_base.py M pywikibot/userinterfaces/gui.py M pywikibot/userinterfaces/terminal_interface_base.py M pywikibot/version.py 25 files changed, 98 insertions(+), 68 deletions(-)

Approvals: Xqt: Looks good to me, approved jenkins-bot: Verified

diff --git a/pywikibot/__init__.py b/pywikibot/__init__.py index e0e55e4..698185b 100644 --- a/pywikibot/__init__.py +++ b/pywikibot/__init__.py @@ -1052,7 +1052,7 @@

This data type is just a json container

- *New in version 3.0.* + .. versionadded:: 3.0 """

_items = ('json',) diff --git a/pywikibot/__metadata__.py b/pywikibot/__metadata__.py index 98f2899..155bdd7 100644 --- a/pywikibot/__metadata__.py +++ b/pywikibot/__metadata__.py @@ -1,6 +1,6 @@ """Pywikibot metadata file.

-*New in version 4.0.* +.. versionadded:: 4.0 """ # # (C) Pywikibot team, 2020-2021 diff --git a/pywikibot/bot_choice.py b/pywikibot/bot_choice.py index 90fc602..822fe9d 100755 --- a/pywikibot/bot_choice.py +++ b/pywikibot/bot_choice.py @@ -95,8 +95,9 @@ def result(self, value: str) -> Any: """Return the actual value which is associated by the given one.

- *New in version 6.2:* *result()* is an abstract method and must - be defined in subclasses + .. versionadded:: 6.2 + *result()* is an abstract method and must be defined in + subclasses """ raise NotImplementedError()

@@ -498,7 +499,7 @@

"""An option to show a list and select an item.

- *New in version 3.0.* + .. versionadded:: 3.0 """

before_question = True @@ -538,7 +539,7 @@

"""An option to select multiple items from a list.

- *New in version 3.0.* + .. versionadded 3.0 """

def test(self, value: str) -> bool: @@ -569,7 +570,7 @@

"""An option to show a list and select multiple items.

- *New in version 3.0.* + .. versionadded 3.0 """

diff --git a/pywikibot/comms/eventstreams.py b/pywikibot/comms/eventstreams.py index c92bc7b..3776e96 100644 --- a/pywikibot/comms/eventstreams.py +++ b/pywikibot/comms/eventstreams.py @@ -7,7 +7,7 @@

pip install sseclient

-*New in version 3.0.* +.. versionadded:: 3.0 """ # # (C) Pywikibot team, 2017-2021 diff --git a/pywikibot/config.py b/pywikibot/config.py index c6bbe26..cd38f22 100644 --- a/pywikibot/config.py +++ b/pywikibot/config.py @@ -25,7 +25,8 @@ - datafilepath - shortpath

-*Renamed in version 6.2* +.. versionchanged 6.2:: + config2 was renamed to config """ # # (C) Pywikibot team, 2003-2021 diff --git a/pywikibot/exceptions.py b/pywikibot/exceptions.py index 0850418..ef76f0f 100644 --- a/pywikibot/exceptions.py +++ b/pywikibot/exceptions.py @@ -470,7 +470,7 @@

"""Missing page history.

- *New in version 6.2.* + .. versionadded:: 6.2 """

message = 'Page %s is invalid.' diff --git a/pywikibot/families/commons_family.py b/pywikibot/families/commons_family.py index 4670ab2..7ac1656 100644 --- a/pywikibot/families/commons_family.py +++ b/pywikibot/families/commons_family.py @@ -42,6 +42,6 @@ def interface(self, code): """Return 'DataSite' to enable structured data.

- *New in version 6.5.* + .. versionadded 6.5 """ return 'DataSite' diff --git a/pywikibot/families/foundation_family.py b/pywikibot/families/foundation_family.py index cc9d7b2..d0b7556 100644 --- a/pywikibot/families/foundation_family.py +++ b/pywikibot/families/foundation_family.py @@ -1,19 +1,21 @@ """Family module for Foundation wiki.

-*New in version 3.0.* +.. versionadded 3.0 """ # -# (C) Pywikibot team, 2019-2020 +# (C) Pywikibot team, 2019-2021 # # Distributed under the terms of the MIT license. # from pywikibot import family

-# The Foundation family class Family(family.WikimediaFamily, family.SingleSiteFamily):

- """Family class for Foundation wiki.""" + """Family class for Foundation wiki. + + .. versionadded 3.0 + """

name = 'foundation' domain = 'foundation.wikimedia.org' diff --git a/pywikibot/families/lingualibre_family.py b/pywikibot/families/lingualibre_family.py index 3e47258..73523ea 100644 --- a/pywikibot/families/lingualibre_family.py +++ b/pywikibot/families/lingualibre_family.py @@ -1,4 +1,7 @@ -"""Family module for Lingua Libre.""" +"""Family module for Lingua Libre. + +.. versionaddded: 6.5 +""" # # (C) Pywikibot team, 2021 # @@ -7,12 +10,11 @@ from pywikibot import family

-# The Lingua Libre family class Family(family.WikimediaFamily):

"""Family class for Lingua Libre.

- *New in version 6.5.* + .. versionaddded: 6.5 """

name = 'lingualibre' diff --git a/pywikibot/families/wikihow_family.py b/pywikibot/families/wikihow_family.py index afe6f85..4aa93f7 100644 --- a/pywikibot/families/wikihow_family.py +++ b/pywikibot/families/wikihow_family.py @@ -1,9 +1,9 @@ """Family module for Wikihow Wiki.

-*New in version 3.0.* +.. versionadded:: 3.0 """ # -# (C) Pywikibot team, 2020 +# (C) Pywikibot team, 2020-2021 # # Distributed under the terms of the MIT license. # @@ -11,7 +11,12 @@ from pywikibot.tools import classproperty

-class Family(family.SubdomainFamily): # noqa: D101 +class Family(family.SubdomainFamily): + + """Family class for Wikihow Wiki. + + .. versionaddded: 3.0 + """

name = 'wikihow' domain = 'wikihow.com' diff --git a/pywikibot/families/wikimania_family.py b/pywikibot/families/wikimania_family.py index 3ba5ba1..aa8c468 100644 --- a/pywikibot/families/wikimania_family.py +++ b/pywikibot/families/wikimania_family.py @@ -1,9 +1,9 @@ """Family module for Wikimania wikis.

-*New in version 3.0.* +.. versionadded:: 3.0 """ # -# (C) Pywikibot team, 2017-2020 +# (C) Pywikibot team, 2017-2021 # # Distributed under the terms of the MIT license. # @@ -14,7 +14,10 @@ # The Wikimania family class Family(family.SubdomainFamily, family.WikimediaFamily):

- """Family class for Wikimania wikis.""" + """Family class for Wikimania wikis. + + .. versionadded:: 3.0 + """

name = 'wikimania'

diff --git a/pywikibot/families/wikispore_family.py b/pywikibot/families/wikispore_family.py index 1dd3037..7178ea9 100644 --- a/pywikibot/families/wikispore_family.py +++ b/pywikibot/families/wikispore_family.py @@ -1,18 +1,21 @@ """Family module for Wikispore.

-*New in version 4.1.* +.. versionadded:: 4.1 """ # -# (C) Pywikibot team, 2020 +# (C) Pywikibot team, 2020-2021 # # Distributed under the terms of the MIT license. # from pywikibot import family

-class Family(family.Family): # noqa: D101 +class Family(family.Family):

- """Family class for Wikispore.""" + """Family class for Wikispore. + + .. versionadded:: 4.1 + """

name = 'wikispore' langs = { diff --git a/pywikibot/family.py b/pywikibot/family.py index abdf7a6..a14d60e 100644 --- a/pywikibot/family.py +++ b/pywikibot/family.py @@ -656,14 +656,14 @@ def get_edit_restricted_templates(self, code): """Return tuple of edit restricted templates.

- *New in version 3.0.* + .. versionadded:: 3.0 """ return self.edit_restricted_templates.get(code, ())

def get_archived_page_templates(self, code): """Return tuple of archived page templates.

- *New in version 3.0.* + .. versionadded:: 3.0 """ return self.archived_page_templates.get(code, ())

@@ -695,7 +695,8 @@ """ Return whether a HTTPS certificate should be verified.

- *Renamed in version 5.3.* + .. versionadded:: 5.3 + renamed from ignore_certificate_error

:param code: language code :return: flag to verify the SSL certificate; @@ -773,14 +774,14 @@ def eventstreams_host(self, code): """Hostname for EventStreams.

- *New in version 3.0.* + .. versionadded:: 3.0 """ raise NotImplementedError('This family does not support EventStreams')

def eventstreams_path(self, code): """Return path for EventStreams.

- *New in version 3.0.* + .. versionadded:: 3.0 """ raise NotImplementedError('This family does not support EventStreams')

@@ -1059,7 +1060,8 @@

"""Common features of Fandom families.

- *Renamed in version 3.0.* + .. versionadded:: 3.0 + renamed from WikiaFamily """

@classproperty diff --git a/pywikibot/page/__init__.py b/pywikibot/page/__init__.py index b8bf88b..f696a0a 100644 --- a/pywikibot/page/__init__.py +++ b/pywikibot/page/__init__.py @@ -1763,7 +1763,7 @@ def has_deleted_revisions(self) -> bool: """Return True if the page has deleted revisions.

- *New in version 4.2.* + .. versionadded:: 4.2 """ if not hasattr(self, '_has_deleted_revisions'): gen = self.site.deletedrevs(self, total=1, prop=['ids']) @@ -2174,7 +2174,7 @@ Return the first 'preferred' ranked Claim specified by Wikibase property or the first 'normal' one otherwise.

- *New in version 3.0.* + .. versionadded:: 3.0

:param prop: property id, "P###" :return: Claim object given by Wikibase property number @@ -2490,7 +2490,7 @@ the method returns the associated mediainfo entity. Otherwise, it falls back to behavior of BasePage.data_item.

- *New in version 6.5.* + .. versionadded:: 6.5

:rtype: pywikibot.page.WikibaseEntity """ @@ -3133,7 +3133,7 @@ ) -> Iterable[Tuple[Page, Revision]]: """Yield tuples describing this user's deleted edits.

- *New in version 5.5.* + .. versionadded:: 5.5

:param total: Limit results to this number of pages :keyword start: Iterate contributions starting at this Timestamp @@ -3435,7 +3435,7 @@

"""Interface for MediaInfo entities on Commons.

- *New in version 6.5.* + .. versionadded:: 6.5 """

title_pattern = r'M[1-9]\d*' @@ -5618,7 +5618,7 @@

- badges: Any badges associated with the sitelink

- *New in version 3.0.* + .. versionadded:: 3.0 """

# Components used for __repr__ diff --git a/pywikibot/pagegenerators.py b/pywikibot/pagegenerators.py index 7f0afcf..f85c0f4 100644 --- a/pywikibot/pagegenerators.py +++ b/pywikibot/pagegenerators.py @@ -1279,7 +1279,7 @@ def handle_args(self, args: Iterable[str]) -> List[str]: """Handle command line arguments and return the rest as a list.

- *New in version 6.0.* + .. versionadded:: 6.0 """ return [arg for arg in args if not self.handle_arg(arg)]

@@ -1292,7 +1292,8 @@ can try parsing the argument. Call getCombinedGenerator() after all arguments have been parsed to get the final output generator.

- *Renamed in version 6.0.* + .. versionadded:: 6.0 + renamed from ``handleArg``

:param arg: Pywikibot argument consisting of -name:value :return: True if the argument supplied was recognised by the factory diff --git a/pywikibot/plural.py b/pywikibot/plural.py index bb4c9d0..45b015d 100644 --- a/pywikibot/plural.py +++ b/pywikibot/plural.py @@ -110,6 +110,6 @@ def plural_rule(lang: str) -> PluralRule: """Return the plural rule for a given lang.

- *New in version 4.3.* + .. versionadded:: 4.3 """ return plural_rules.get(lang, plural_rules['_default']) diff --git a/pywikibot/site/_apisite.py b/pywikibot/site/_apisite.py index eb2623e..67ea3ed 100644 --- a/pywikibot/site/_apisite.py +++ b/pywikibot/site/_apisite.py @@ -1417,7 +1417,7 @@ If more than one target id is provided, the same action is taken for all of them.

- *New in version 6.0.* + .. versionadded:: 6.0

:param targettype: Type of target. One of "archive", "filearchive", "logging", "oldimage", "revision". @@ -2048,9 +2048,11 @@ To delete a specific version of an image the oldimage identifier must be provided.

- *Renamed in version 6.1.* + .. versionadded:: 6.1 + renamed from *deletepage*

- *New in version 6.1:* keyword only parameter *oldimage* was added. + .. versionchanged:: 6.1 + keyword only parameter *oldimage* was added.

:param page: Page to be deleted or its pageid. :type page: :py:obj:`pywikibot.page.BasePage` or, for pageid, @@ -2111,11 +2113,12 @@

:see: https://www.mediawiki.org/wiki/API:Undelete

- *Renamed in version 6.1.* + .. versionadded:: 6.1 + renamed from *undelete_page*

- *New in version 6.1:* *fileids* parameter was added. - - *Changed in verson 6.1:* keyword argument required for *revisions*. + .. versionchanged:: 6.1 + *fileids* parameter was added, + keyword argument required for *revisions*.

:param page: Page to be deleted. :type page: pywikibot.BasePage @@ -2461,11 +2464,11 @@

Either source_filename or source_url, but not both, must be provided.

- *Changed in version 6.0:* keyword arguments required for all - parameters except *filepage*. + .. versionchanged:: 6.0 + keyword arguments required for all parameters except *filepage*

- *Changed in version 6.2:* asynchronous upload is used if - *asynchronous* parameter is set. + .. versionchanged:: 6.2: + asynchronous upload is used if *asynchronous* parameter is set.

:param filepage: a FilePage object from which the wiki-name of the file will be obtained. diff --git a/pywikibot/site/_generators.py b/pywikibot/site/_generators.py index 2314a13..ca50567 100644 --- a/pywikibot/site/_generators.py +++ b/pywikibot/site/_generators.py @@ -706,7 +706,8 @@ include_empty_titles: bool = False): """Iterate all interlanguage links on page, yielding Link objects.

- *New in version 6.2:* *include_empty_titles* parameter was added. + .. versionchanged:: 6.2: + *include_empty_titles* parameter was added.

:see: https://www.mediawiki.org/wiki/API:Langlinks

diff --git a/pywikibot/site_detect.py b/pywikibot/site_detect.py index 1b81fc2..6868b52 100644 --- a/pywikibot/site_detect.py +++ b/pywikibot/site_detect.py @@ -275,7 +275,7 @@ def check_response(response): """Raise ServerError if the response indicates a server error.

- *New in version 3.0.* + .. versionadded:: 3.0 """ if response.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR: raise ServerError(HTTPStatus(response.status_code).phrase) diff --git a/pywikibot/specialbots/_upload.py b/pywikibot/specialbots/_upload.py index f3babaf..e3cf7e9 100644 --- a/pywikibot/specialbots/_upload.py +++ b/pywikibot/specialbots/_upload.py @@ -49,10 +49,11 @@ **kwargs): """Initializer.

- *Changed in version 6.2:* asynchronous upload is used if - *asynchronous* parameter is set. + .. versionchanged:: 6.2 + asynchronous upload is used if *asynchronous* parameter is set

- *New in version 6.4:* force_if_shared parameter. + .. versionchanged:: 6.4 + *force_if_shared* parameter was added

:param url: path to url or local file, or list of urls or paths to local files. diff --git a/pywikibot/textlib.py b/pywikibot/textlib.py index ec06c67..0b9668e 100644 --- a/pywikibot/textlib.py +++ b/pywikibot/textlib.py @@ -826,7 +826,7 @@ def add_text(text: str, add: str, *, site=None) -> str: """Add text to a page content above categories and interwiki.

- *New in version 6.4.* + .. versionadded:: 6.4

:param text: The page content to add text to. :param add: Text to add. @@ -925,7 +925,7 @@ ('== Usage of A ==', 'Some usage...')] result.footer = '[[Category:Things starting with A]]'

- *New in version 3.0.* + .. versionadded:: 3.0 """ headings = _extract_headings(text, site) sections = _extract_sections(text, headings) @@ -1636,8 +1636,9 @@ :param strip: If enabled, strip arguments and values of templates. :return: list of template name and params

- *New in version 6.1:* *wikitextparser* package is supported; either - *wikitextparser* or *mwparserfromhell* is strictly recommended. + .. versionchanged:: 6.1 + *wikitextparser* package is supported; either *wikitextparser* or + *mwparserfromhell* is strictly recommended. """ def explicit(param): try: diff --git a/pywikibot/userinterfaces/_interface_base.py b/pywikibot/userinterfaces/_interface_base.py index b25b160..422496e 100644 --- a/pywikibot/userinterfaces/_interface_base.py +++ b/pywikibot/userinterfaces/_interface_base.py @@ -1,6 +1,6 @@ """Abstract base user interface module.

-*New in version 6.2.* +.. versionadded:: 6.2 """ # # (C) Pywikibot team, 2021 @@ -21,6 +21,8 @@

Every user interface should derive from it to ensure that all required methods are implemented. + + .. versionadded:: 6.2 """

def argvu(self) -> List[str]: diff --git a/pywikibot/userinterfaces/gui.py b/pywikibot/userinterfaces/gui.py index b9a7713..9324f4b 100644 --- a/pywikibot/userinterfaces/gui.py +++ b/pywikibot/userinterfaces/gui.py @@ -3,7 +3,8 @@

Useful for editing the contents of an article.

-*New in version 6.1:* Python 3.6 or highter is required. +.. versionchanged:: 6.1 + Python 3.6 or highter is required. """ # # (C) Pywikibot team, 2003-2021 diff --git a/pywikibot/userinterfaces/terminal_interface_base.py b/pywikibot/userinterfaces/terminal_interface_base.py index 5a94d6e..c288bdc 100755 --- a/pywikibot/userinterfaces/terminal_interface_base.py +++ b/pywikibot/userinterfaces/terminal_interface_base.py @@ -57,8 +57,9 @@

"""Base for terminal user interfaces.

- *New in version 6.2:* subclassed from - :py:obj:`pywikibot.userinterfaces._interface_base.ABUIC`. + .. versionchanged:: 6.2: + subclassed from + :py:obj:`pywikibot.userinterfaces._interface_base.ABUIC` """

split_col_pat = re.compile(r'(\w+);?(\w+)?') diff --git a/pywikibot/version.py b/pywikibot/version.py index 3bc2e86..26597cc 100644 --- a/pywikibot/version.py +++ b/pywikibot/version.py @@ -40,7 +40,7 @@ def get_toolforge_hostname() -> Optional[str]: """Get hostname of the current Toolforge host.

- *New in version 3.0.* + .. versionadded:: 3.0

:return: The hostname of the currently running host, if it is in Wikimedia Toolforge; otherwise return None.