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

Change subject: [doc] Update documentation ......................................................................

[doc] Update documentation

Change-Id: I1f1c1c74650d278377d447b3569bf9aaeca8d1fc --- M pywikibot/bot.py M pywikibot/cosmetic_changes.py M pywikibot/data/api/_generators.py M pywikibot/diff.py M pywikibot/page/_filepage.py M pywikibot/page/_pages.py M pywikibot/pagegenerators.py M pywikibot/scripts/login.py M pywikibot/site/_datasite.py M pywikibot/site/_siteinfo.py M pywikibot/site/_upload.py M pywikibot/tools/__init__.py M scripts/data_ingestion.py M scripts/harvest_template.py M scripts/welcome.py M tests/site_tests.py M tests/thanks_tests.py 17 files changed, 90 insertions(+), 73 deletions(-)

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

diff --git a/pywikibot/bot.py b/pywikibot/bot.py index 012319f..f401d96 100644 --- a/pywikibot/bot.py +++ b/pywikibot/bot.py @@ -2257,7 +2257,8 @@ Before adding a new claim, it checks if we can add it, using provided filters.

- :see: documentation of :py:obj:`claimit.py<scripts.claimit>` + ..seealso:: documentation of :py:obj:`claimit.py<scripts.claimit>` + :param exists_arg: pattern for merging existing claims with new ones :param logger_callback: function logging the output of the method :return: whether the claim could be added diff --git a/pywikibot/cosmetic_changes.py b/pywikibot/cosmetic_changes.py index 54e1ccb..5f06e80 100644 --- a/pywikibot/cosmetic_changes.py +++ b/pywikibot/cosmetic_changes.py @@ -748,11 +748,11 @@

== Section title ==

- :NOTE: This space is recommended in the syntax help on the - English and German Wikipedias. It is not wanted on Lojban and - English Wiktionaries (T168399, T169064) and it might be that - it is not wanted on other wikis. If there are any complaints, - please file a bug report. + .. note:: This space is recommended in the syntax help on the + English and German Wikipedias. It is not wanted on Lojban and + English Wiktionaries (:phab:`T168399`, :phab:`T169064`) and + it might be that it is not wanted on other wikis. If there + are any complaints, please file a bug report. """ if self.site.sitename in ['wiktionary:jbo', 'wiktionary:en']: return text @@ -766,10 +766,10 @@ """ Add a space between the * or # and the text.

- :NOTE: This space is recommended in the syntax help on the - English, German and French Wikipedias. It might be that it - is not wanted on other wikis. If there are any complaints, - please file a bug report. + .. note:: This space is recommended in the syntax help on the + English, German and French Wikipedias. It might be that it + is not wanted on other wikis. If there are any complaints, + please file a bug report. """ if not self.template: exceptions = ['comment', 'math', 'nowiki', 'pre', diff --git a/pywikibot/data/api/_generators.py b/pywikibot/data/api/_generators.py index e2b4a10..04fe660 100644 --- a/pywikibot/data/api/_generators.py +++ b/pywikibot/data/api/_generators.py @@ -384,9 +384,9 @@ def support_namespace(self) -> bool: """Check if namespace is a supported parameter on this query.

- Note: this function will be removed when self.set_namespace() will - throw TypeError() instead of just giving a warning. - See T196619. + .. note:: this function will be removed when + :meth:`set_namespace` will throw TypeError() instead of just + giving a warning. See :phab:`T196619`.

:return: True if yes, False otherwise """ diff --git a/pywikibot/diff.py b/pywikibot/diff.py index d67a8b9..9c94077 100644 --- a/pywikibot/diff.py +++ b/pywikibot/diff.py @@ -22,7 +22,8 @@

"""One change hunk between a and b.

- Note: parts of this code are taken from by difflib.get_grouped_opcodes(). + .. note:: parts of this code are taken from by + `difflib.get_grouped_opcodes()`.

"""

diff --git a/pywikibot/page/_filepage.py b/pywikibot/page/_filepage.py index 0e61412..c8983a9 100644 --- a/pywikibot/page/_filepage.py +++ b/pywikibot/page/_filepage.py @@ -239,9 +239,11 @@ codes for which an equivalent callable would return True if all UploadError codes are in thet list. If the result is False it'll not continue uploading the file and otherwise disable any warning - and reattempt to upload the file. NOTE: If report_success is True - or None it'll raise an UploadError exception if the static - boolean is False. + and reattempt to upload the file. + + .. note:: NOTE: If report_success is True or None it'll + raise an UploadError exception if the static boolean is + False. :type ignore_warnings: bool or callable or iterable of str :keyword chunk_size: The chunk size in bytesfor chunked uploading (see :api:`Upload#Chunked_uploading`). It will diff --git a/pywikibot/page/_pages.py b/pywikibot/page/_pages.py index 2021b09..1ddeba3 100644 --- a/pywikibot/page/_pages.py +++ b/pywikibot/page/_pages.py @@ -2543,7 +2543,10 @@ """ return self.site.categoryinfo(self)

- def newest_pages(self, total=None): + def newest_pages( + self, + total: Optional[int] = None + ) -> Generator[Page, None, None]: """ Return pages in a category ordered by the creation date.

@@ -2560,12 +2563,12 @@ checked).

:param total: The total number of pages queried. - :type total: int :return: A page generator of all pages in a category ordered by the - creation date. From newest to oldest. Note: It currently only - returns Page instances and not a subclass of it if possible. This - might change so don't expect to only get Page instances. - :rtype: generator + creation date. From newest to oldest. + + .. note:: It currently only returns Page instances and not a + subclass of it if possible. This might change so don't + expect to only get Page instances. """ def check_cache(latest): """Return the cached pages in order and not more than total.""" diff --git a/pywikibot/pagegenerators.py b/pywikibot/pagegenerators.py index 3450499..10ac283 100644 --- a/pywikibot/pagegenerators.py +++ b/pywikibot/pagegenerators.py @@ -110,22 +110,22 @@ across all namespaces.

-logevents Work on articles that were on a specified Special:Log. - The value may be a comma separated list of these values: + The value may be a comma separated list of these values::

logevent,username,start,end

- or for backward compatibility: + or for backward compatibility::

logevent,username,total

- Note: 'start' is the most recent date and log events are - iterated from present to past. If 'start'' is not provided, - it means 'now'; if 'end' is not provided, it means 'since - the beginning'. + .. note:: 'start' is the most recent date and log + events are iterated from present to past. If + 'start' is not provided, it means 'now'; if 'end' + is not provided, it means 'since the beginning'.

To use the default value, use an empty string. You have options for every type of logs given by the - log event parameter which could be one of the following: + log event parameter which could be one of the following::

spamblacklist, titleblacklist, gblblock, renameuser, globalauth, gblrights, gblrename, abusefilter, @@ -251,7 +251,7 @@ and works on the resulting pages.

-sparqlendpoint Specify SPARQL endpoint URL (optional). - (Example : -sparqlendpoint:http://myserver.com/sparql) + (Example: -sparqlendpoint:http://myserver.com/sparql)

-searchitem Takes a search string and works on Wikibase pages that contain it. @@ -350,14 +350,14 @@ -namespace specified namespaces. Separate multiple namespace -ns numbers or names with commas.

- Examples: + Examples::

-ns:0,2,4 -ns:Help,MediaWiki

You may use a preleading "not" to exclude the namespace.

- Examples: + Examples::

-ns:not:2,3 -ns:not:Help,File @@ -378,19 +378,23 @@

Examples:

- P1=Q2 (property P1 must contain value Q2), - P3=Q4,P5=Q6,P6=Q7 (property P3 with value Q4 and - qualifiers: P5 with value Q6 and P6 with value Q7). + .. code-block:: shell + + P1=Q2 (property P1 must contain value Q2), + P3=Q4,P5=Q6,P6=Q7 (property P3 with value Q4 and + qualifiers: P5 with value Q6 and P6 with value Q7). + Value can be page ID, coordinate in format: latitude,longitude[,precision] (all values are in decimal degrees), year, or plain string. + The argument can be provided multiple times and the item page will be returned only if all claims are present. Argument can be also given as "-onlyif:expression".

--onlyifnot A claim the page must not contain, otherwise the item won't - be returned. - For usage and examples, see -onlyif above. +-onlyifnot A claim the page must not contain, otherwise the + item won't be returned. For usage and examples, see + `-onlyif` above.

-ql Filter pages based on page quality. This is only applicable if contentmodel equals @@ -1743,13 +1747,13 @@ return gen

-def NamespaceFilterPageGenerator(generator: Iterable['pywikibot.page.Page'], - namespaces: Union[ - FrozenSet['pywikibot.site.Namespace'], - NAMESPACE_OR_STR_TYPE, - Sequence[NAMESPACE_OR_STR_TYPE]], - site: OPT_SITE_TYPE = None - ) -> Iterator['pywikibot.page.Page']: +def NamespaceFilterPageGenerator( + generator: Iterable['pywikibot.page.Page'], + namespaces: Union[FrozenSet['pywikibot.site.Namespace'], + NAMESPACE_OR_STR_TYPE, + Sequence[NAMESPACE_OR_STR_TYPE]], + site: OPT_SITE_TYPE = None +) -> Iterator['pywikibot.page.Page']: """ A generator yielding pages from another generator in given namespaces.

@@ -1757,8 +1761,8 @@ of that site, otherwise the namespaces are validated using the default site.

- NOTE: API-based generators that have a "namespaces" parameter perform - namespace filtering more efficiently than this generator. + .. note:: API-based generators that have a "namespaces" parameter + perform namespace filtering more efficiently than this generator.

:param namespaces: list of namespace identifiers to limit results :param site: Site for generator results; mandatory if @@ -1977,8 +1981,9 @@ Uses regex option re.IGNORECASE depending on the quantifier parameter.

If ignore_namespace is False, the whole page title is compared. - NOTE: if you want to check for a match at the beginning of the title, - you have to start the regex with "^" + + .. note:: if you want to check for a match at the beginning of + the title, you have to start the regex with "^"

:param generator: another generator :param regex: a regex which should match the page title diff --git a/pywikibot/scripts/login.py b/pywikibot/scripts/login.py index b4627c2..e45273b 100755 --- a/pywikibot/scripts/login.py +++ b/pywikibot/scripts/login.py @@ -21,11 +21,14 @@ site.

-oauth Generate OAuth authentication information. - NOTE: Need to copy OAuth tokens to your user-config.py - manually. -logout is not compatible with -oauth. + + .. note:: Need to copy OAuth tokens to your user-config.py + manually. -logout is not compatible with -oauth.

-autocreate Auto-create an account using unified login when necessary. - Note: the global account must exist already before using this. + + .. note:: the global account must exist already before + using this.

If not given as parameter, the script will ask for your username and password (password entry will be hidden), log in to your home wiki using diff --git a/pywikibot/site/_datasite.py b/pywikibot/site/_datasite.py index a3e2215..5375cc7 100644 --- a/pywikibot/site/_datasite.py +++ b/pywikibot/site/_datasite.py @@ -247,11 +247,11 @@

@need_right('edit') def editEntity(self, entity, data, bot: bool = True, **kwargs): - """ - Edit entity. + """Edit entity.

- Note: This method is unable to create entities other than 'item' - if dict with API parameters was passed to 'entity' parameter. + .. note:: This method is unable to create entities other than + 'item' if dict with API parameters was passed to 'entity' + parameter.

:param entity: Page to edit, or dict with API parameters to use for entity identification diff --git a/pywikibot/site/_siteinfo.py b/pywikibot/site/_siteinfo.py index 92d2563..00e90f6 100644 --- a/pywikibot/site/_siteinfo.py +++ b/pywikibot/site/_siteinfo.py @@ -265,6 +265,8 @@ It will never throw an APIError if it only stated, that the siteinfo property doesn't exist. Instead it will use the default value.

+ .. seealso:: :py:obj:`_get_siteinfo` + :param key: The name of the siteinfo property. :param get_default: Whether to throw an KeyError if the key is invalid. :param cache: Caches the result internally so that future accesses via @@ -274,7 +276,6 @@ :return: The gathered property :raises KeyError: If the key is not a valid siteinfo property and the get_default option is set to False. - :see: :py:obj:`_get_siteinfo` """ # If expiry is True, convert it to 0 to be coherent with # _get_siteinfo() and _get_general() docstring. diff --git a/pywikibot/site/_upload.py b/pywikibot/site/_upload.py index ad4af5a..c91e689 100644 --- a/pywikibot/site/_upload.py +++ b/pywikibot/site/_upload.py @@ -51,9 +51,10 @@ codes for which an equivalent callable would return True if all UploadError codes are in thet list. If the result is False it'll not continue uploading the file and otherwise disable any warning - and reattempt to upload the file. NOTE: If report_success is True - or None it'll raise an UploadError exception if the static - boolean is False. + and reattempt to upload the file. + + .. note:: If report_success is True or None it'll raise an + UploadError exception if the static boolean is False. :type ignore_warnings: bool or callable or iterable of str :param report_success: If the upload was successful it'll print a success message and if ignore_warnings is set to False it'll diff --git a/pywikibot/tools/__init__.py b/pywikibot/tools/__init__.py index 9bc7ad0..92786ba 100644 --- a/pywikibot/tools/__init__.py +++ b/pywikibot/tools/__init__.py @@ -978,7 +978,7 @@

Beware that key=id is only useful for cases where id() is not unique.

- Note: This is not thread safe. + .. warning:: This is not thread safe.

.. versionadded: 3.0

diff --git a/scripts/data_ingestion.py b/scripts/data_ingestion.py index ac83770..802cf05 100755 --- a/scripts/data_ingestion.py +++ b/scripts/data_ingestion.py @@ -172,8 +172,8 @@ """ Populate format string with %(name)s entries using metadata.

- Note: this does not clean the title, so it may be unusable as - a MediaWiki page title, and cause an API exception when used. + .. note:: this does not clean the title, so it may be unusable as + a MediaWiki page title, and cause an API exception when used.

:param fmt: format string :return: formatted string diff --git a/scripts/harvest_template.py b/scripts/harvest_template.py index 38d58f9..c1df570 100755 --- a/scripts/harvest_template.py +++ b/scripts/harvest_template.py @@ -243,7 +243,7 @@ """ Compare bot's (global) and provided (local) options.

- :see: :py:obj:`OptionHandler` + .. seealso:: :class:`OptionHandler` """ default = self.opt[option] local = handler.opt[option] diff --git a/scripts/welcome.py b/scripts/welcome.py index 14b1573..b1f3feb 100755 --- a/scripts/welcome.py +++ b/scripts/welcome.py @@ -139,8 +139,8 @@ * [[User:Rock|Rock]] </pre>

-NOTE: The white space and <pre></pre> aren't required but I suggest you to - use them. +.. note:: The white space and <pre></pre> aren't required but I suggest + you to use them.

******************************** Badwords **********************************

diff --git a/tests/site_tests.py b/tests/site_tests.py index ec46674..c4c209e 100755 --- a/tests/site_tests.py +++ b/tests/site_tests.py @@ -1060,9 +1060,9 @@

If there are no images included in main page it'll skip all tests.

- Note: This is not implemented as setUpClass which would be invoked - while initialising all tests, to reduce chance of an error preventing - all tests from running. + .. note:: This is not implemented as setUpClass which would be + invoked while initialising all tests, to reduce chance of an + error preventing all tests from running. """ if hasattr(self.__class__, '_image_page'): return self.__class__._image_page diff --git a/tests/thanks_tests.py b/tests/thanks_tests.py index c7a1422..137d1e0 100755 --- a/tests/thanks_tests.py +++ b/tests/thanks_tests.py @@ -28,9 +28,9 @@ def test_thank_revision(self): """Test thanks for normal revisions.

- NOTE: This test relies on activity in recentchanges, and - there must make edits made before reruns of this test. - Please see https://phabricator.wikimedia.org/T137836. + .. note:: This test relies on activity in recentchanges, and + there must make edits made before reruns of this test. + .. seealso:: :phab:`T137836`. """ site = self.get_site() data = site.recentchanges(total=20)