jenkins-bot submitted this change.
[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(-)
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
To view, visit change 674415. To unsubscribe, or for help writing mail filters, visit settings.