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

Change subject: [doc] remove epydoc stuff ......................................................................

[doc] remove epydoc stuff

- remove pywikibot_epytext_to_sphinx function - replace epytext tokens with sphinx counterparts - update deprecation tests - update deprecation notice with @deprecated decorator

Bug: T308985 Change-Id: I41fc77f7b7bb942bb06cb8a7a3050ecd43c8d71c --- M docs/conf.py M pywikibot/bot_choice.py M pywikibot/data/api.py M pywikibot/page/_pages.py M pywikibot/site/_datasite.py M pywikibot/tools/_deprecate.py M scripts/archivebot.py M scripts/dataextend.py M scripts/redirect.py M scripts/replace.py M tests/deprecation_tests.py 11 files changed, 34 insertions(+), 86 deletions(-)

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

diff --git a/docs/conf.py b/docs/conf.py index 1b2a310..ec0e077 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -377,59 +377,6 @@ }

-TOKENS_WITH_PARAM = [ - # sphinx - 'param', 'parameter', 'arg', 'argument', 'key', 'keyword', - 'type', - 'raises', 'raise', 'except', 'exception', - 'var', 'ivar', 'cvar', - 'vartype', - 'meta', - # epytext - 'todo', -] - -TOKENS = [ - # sphinx - 'return', 'returns', 'rtype', - # epytext - 'attention', 'author', 'bug', - 'change', 'changed', - 'contact', - 'copyright', '(c)', - 'deprecated', - 'invariant', 'license', 'note', - 'organization', 'org', - 'permission', - 'postcondition', 'postcond', - 'precondition', 'precond', - 'requires', 'require', 'requirement', - 'see', 'seealso', - 'since', 'status', 'summary', 'todo', - 'version', - 'warn', 'warning', -] - - -def pywikibot_epytext_to_sphinx(app, what, name, obj, options, lines): - """Convert epytext tokens to sphinx.""" - result = [] - for line in lines: - line = re.sub(r'(\A *)@({}) '.format('|'.join(TOKENS_WITH_PARAM)), - r'\1:\2 ', line) # tokens with parameter - line = re.sub(r'(\A *)@({}):'.format('|'.join(TOKENS)), - r'\1:\2:', line) # short token - line = re.sub(r'(\A *)@(?:kwarg|kwparam) ', - r'\1:keyword ', line) # keyword - line = re.sub(r'(\A| )L{([^}]*)}', r'\1:py:obj:`\2`', line) # Link - line = re.sub(r'(\A| )B{([^}]*)}', r'\1**\2**', line) # Bold - line = re.sub(r'(\A| )I{([^}]*)}', r'\1*\2*', line) # Italic - line = re.sub(r'(\A| )C{([^}]*)}', r'\1``\2``', line) # Code - line = re.sub(r'(\A| )U{([^}]*)}', r'\1\2', line) # Url - result.append(line) - lines[:] = result[:] # assignment required in this way - - def pywikibot_fix_phab_tasks(app, what, name, obj, options, lines): """Convert Phabricator tasks id to a link using sphinx.ext.extlinks.""" result = [] @@ -541,7 +488,6 @@

def setup(app): """Implicit Sphinx extension hook.""" - app.connect('autodoc-process-docstring', pywikibot_epytext_to_sphinx) app.connect('autodoc-process-docstring', pywikibot_fix_phab_tasks) app.connect('autodoc-process-docstring', pywikibot_docstring_fixups) app.connect('autodoc-process-docstring', pywikibot_script_docstring_fixups) diff --git a/pywikibot/bot_choice.py b/pywikibot/bot_choice.py index 8e4e7b3..040f06f 100644 --- a/pywikibot/bot_choice.py +++ b/pywikibot/bot_choice.py @@ -125,7 +125,9 @@ def out(self) -> str: """String to be used when selected before or after the question.

- :Note: This method is used by ui.input_choice instead of output(). + .. note:: This method is used by :meth:`ui.input_choice + <pywikibot.userinterfaces._interface_base.ABUIC.input_choice>` + instead of deprecated :meth:`output`.

.. versionadded:: 6.2 """ @@ -136,7 +138,7 @@ """Output string.

.. deprecated:: 6.5 - This method was replaced by :py:obj:`out` property and is no + This method was replaced by :attr:`out` property and is no no longer used by the :py:mod:`userinterfaces <pywikibot.userinterfaces>` system. """ diff --git a/pywikibot/data/api.py b/pywikibot/data/api.py index 8e821da..ab01827 100644 --- a/pywikibot/data/api.py +++ b/pywikibot/data/api.py @@ -2456,13 +2456,12 @@ namespace identifiers. An empty iterator clears any namespace restriction. :raises KeyError: a namespace identifier was not resolved - + """ # TODO: T196619 - # @raises TypeError: module does not support a namespace parameter + # :raises TypeError: module does not support a namespace parameter # or a namespace identifier has an inappropriate # type such as NoneType or bool, or more than one namespace # if the API module does not support multiple namespaces - """ assert self.limited_module # some modules do not have a prefix param = self.site._paraminfo.parameter('query+' + self.limited_module, 'namespace') diff --git a/pywikibot/page/_pages.py b/pywikibot/page/_pages.py index 848b7c0..aa5d930 100644 --- a/pywikibot/page/_pages.py +++ b/pywikibot/page/_pages.py @@ -1077,8 +1077,8 @@ def _check_bot_may_edit(self, module: Optional[str] = None) -> bool: """A botMayEdit helper method.

- @param module: The module name to be restricted. Defaults to - pywikibot.calledModuleName(). + :param module: The module name to be restricted. Defaults to + :func:`pywikibot.calledModuleName`. """ if not hasattr(self, 'templatesWithParams'): return True diff --git a/pywikibot/site/_datasite.py b/pywikibot/site/_datasite.py index 440134e..097928a 100644 --- a/pywikibot/site/_datasite.py +++ b/pywikibot/site/_datasite.py @@ -713,7 +713,8 @@ return gen

@need_right('edit') - def _wbset_action(self, itemdef, action, action_data, **kwargs): + def _wbset_action(self, itemdef, action: str, action_data, + **kwargs) -> dict: """ Execute wbset{action} on a Wikibase entity.

@@ -724,9 +725,8 @@ :type itemdef: str, WikibaseEntity or Page connected to such item :param action: wbset{action} to perform: 'wbsetaliases', 'wbsetdescription', 'wbsetlabel', 'wbsetsitelink' - :type action: str - :param data: data to be used in API request, see API help - :type data: SiteLink or dict + :param action_data: data to be used in API request, see API help + :type action_data: SiteLink or dict wbsetaliases: dict shall have the following structure: {'language': value (str), @@ -740,12 +740,11 @@ wbsetsitelink: dict shall have keys 'linksite', 'linktitle' and optionally 'badges' - @kwargs bot: Whether to mark the edit as a bot edit, default is True + :keyword bot: Whether to mark the edit as a bot edit, default is True :type bot: bool - @kwargs tags: Change tags to apply with the edit + :keyword tags: Change tags to apply with the edit :type tags: list of str :return: query result - :rtype: dict :raises AssertionError, TypeError """ def format_sitelink(sitelink): diff --git a/pywikibot/tools/_deprecate.py b/pywikibot/tools/_deprecate.py index bff6759..22da253 100644 --- a/pywikibot/tools/_deprecate.py +++ b/pywikibot/tools/_deprecate.py @@ -270,9 +270,9 @@ if not deprecated_notice.search(wrapper.__doc__): add_docstring(wrapper) else: - # Get docstring up to @params so deprecation notices for + # Get docstring up to :params so deprecation notices for # parameters don't disrupt it - trim_params = re.compile(r'^.*?((?=@param)|$)', re.DOTALL) + trim_params = re.compile(r'^.*?((?=:param)|$)', re.DOTALL) trimmed_doc = trim_params.match(wrapper.__doc__).group(0)

if not deprecated_notice.search(trimmed_doc): # No notice diff --git a/scripts/archivebot.py b/scripts/archivebot.py index 6d53efc..41609eb 100755 --- a/scripts/archivebot.py +++ b/scripts/archivebot.py @@ -268,7 +268,7 @@ 150K - 150 kilobytes 2M - 2 megabytes

- @Returns: a tuple ``(size, unit)``, where ``size`` is an integer and + :Returns: a tuple ``(size, unit)``, where ``size`` is an integer and unit is ``'B'`` (bytes) or ``'T'`` (threads). """ match = re.fullmatch(r'(\d{1,3}(?: \d{3})+|\d+) *([BkKMT]?)', string) diff --git a/scripts/dataextend.py b/scripts/dataextend.py index 1411475..5792aee 100644 --- a/scripts/dataextend.py +++ b/scripts/dataextend.py @@ -15413,7 +15413,7 @@

If args is an empty list, sys.argv is used.

- @param args: command line arguments + :param args: command line arguments """ item = None options = {} diff --git a/scripts/redirect.py b/scripts/redirect.py index 4488167..9029760 100755 --- a/scripts/redirect.py +++ b/scripts/redirect.py @@ -457,13 +457,12 @@ self.is_repo = self.repo if self.repo == page.site else None return page

- def delete_redirect(self, page, summary_key) -> None: + def delete_redirect(self, page, summary_key: str) -> None: """Delete the redirect page.

- @param page: The page to delete - @type page: pywikibot.page.BasePage - @param summary_key: The message key for the deletion summary - @type summary_key: str + :param page: The page to delete + :type page: pywikibot.page.BasePage + :param summary_key: The message key for the deletion summary """ assert page.site == self.current_page.site, ( 'target page is on different site {}'.format(page.site)) @@ -666,8 +665,8 @@ def treat(self, page) -> None: """Treat a page.

- @param page: Page to be treated. - @type page: pywikibot.page.BasePage + :param page: Page to be treated. + :type page: pywikibot.page.BasePage """ if self.counter['read'] >= self.opt.limit: pywikibot.output('\nNumber of pages reached the limit. ' diff --git a/scripts/replace.py b/scripts/replace.py index 3e932e8..b8c0ae0 100755 --- a/scripts/replace.py +++ b/scripts/replace.py @@ -510,7 +510,6 @@ :type allowoverlap: bool :keyword recursive: Recurse replacement as long as possible. :type recursive: bool - :warning: Be careful, this might lead to an infinite loop. :keyword addcat: category to be added to every page touched :type addcat: pywikibot.Category or str or None :keyword sleep: slow down between processing multiple regexes @@ -520,9 +519,12 @@ :keyword always: the user won't be prompted before changes are made :type keyword: bool :keyword site: Site the bot is working on. - :warning: site parameter should be passed to constructor. - Otherwise the bot takes the current site and warns the operator - about the missing site + .. warning:: + - Be careful with `recursive` parameter, this might lead to an + infinite loop. + - `site` parameter should be passed to constructor. + Otherwise the bot takes the current site and warns the operator + about the missing site """

def __init__(self, generator, diff --git a/tests/deprecation_tests.py b/tests/deprecation_tests.py index 649fb42..a0efea2 100755 --- a/tests/deprecation_tests.py +++ b/tests/deprecation_tests.py @@ -122,7 +122,7 @@

@deprecated def deprecated_func_docstring_arg(foo=None): - """@param foo: Foo. DEPRECATED.""" + """:param foo: Foo. DEPRECATED.""" return foo

@@ -308,12 +308,13 @@ (deprecated_func_instead_docstring, "DEPRECATED, don't use " 'this. Deprecated function.'), (deprecated_func_docstring_arg, 'Deprecated.\n\n' - '@param foo: Foo. DEPRECATED.'), + ':param foo: Foo. DEPRECATED.'), (deprecated_func_docstring_arg2, '\n DEPRECATED.\n\n' ' :param foo: Foo. DEPRECATED.\n '), ] for rv, doc in testcases: - self.assertEqual(rv.__doc__, doc) + with self.subTest(function=rv.__name__): + self.assertEqual(rv.__doc__, doc)

def test_deprecated_function_bad_args(self): """Test @deprecated function with bad arguments."""