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

Change subject: [doc] convert epytext documenation to sphinx ......................................................................

[doc] convert epytext documenation to sphinx

- replace sphinx_epytext package by our own pywikibot_epytext_to_sphinx functions which solves problems with @deprecated decorators. Additional improvements: - convert bold and italic tokens - fix code token - add ivar and cvar token - remove sphinx_epytext requirement

Change-Id: Ia8ca82cda54c8a4142cdd96622d89b4d95a67bfc --- M docs/conf.py M docs/requirements-py3.txt 2 files changed, 56 insertions(+), 4 deletions(-)

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

diff --git a/docs/conf.py b/docs/conf.py index 7d4363a..3ac6b02 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,7 +44,6 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = ['sphinx.ext.autodoc', - 'sphinx_epytext', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', @@ -89,7 +88,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -# language = None +language = None

# There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -345,6 +344,59 @@ # texinfo_no_detailmenu = False

+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| )C{([^}]*)}', 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_script_docstring_fixups(app, what, name, obj, options, lines): """Pywikibot specific conversions.""" from scripts.cosmetic_changes import warning @@ -434,6 +486,7 @@

def setup(app): """Implicit Sphinx extension hook.""" + app.connect('autodoc-process-docstring', pywikibot_epytext_to_sphinx) app.connect('autodoc-process-docstring', pywikibot_script_docstring_fixups) app.connect('autodoc-skip-member', pywikibot_skip_members) app.add_autodoc_attrgetter(type, pywikibot_family_classproperty_getattr) diff --git a/docs/requirements-py3.txt b/docs/requirements-py3.txt index 939b930..4d9bfe4 100644 --- a/docs/requirements-py3.txt +++ b/docs/requirements-py3.txt @@ -1,5 +1,4 @@ # This is a PIP requirements file for building Sphinx documentation of pywikibot # requirements.txt is also needed

-sphinx >= 1.8, != 3.1.0, != 3.5.0 -sphinx-epytext >= 0.0.4 \ No newline at end of file +sphinx >= 1.8, != 3.1.0, != 3.5.0 \ No newline at end of file