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."""
--
To view, visit https://gerrit.wikimedia.org/r/c/pywikibot/core/+/795282
To unsubscribe, or for help writing mail filters, visit
https://gerrit.wikimedia.org/r/settings
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Change-Id: I41fc77f7b7bb942bb06cb8a7a3050ecd43c8d71c
Gerrit-Change-Number: 795282
Gerrit-PatchSet: 3
Gerrit-Owner: Xqt <[email protected]>
Gerrit-Reviewer: D3r1ck01 <[email protected]>
Gerrit-Reviewer: Xqt <[email protected]>
Gerrit-Reviewer: jenkins-bot
Gerrit-MessageType: merged
_______________________________________________
Pywikibot-commits mailing list -- [email protected]
To unsubscribe send an email to [email protected]
