Xqt has submitted this change. (
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/818531
)
Change subject: [sphinx] Require sphinx >= 5.1.1
......................................................................
[sphinx] Require sphinx >= 5.1.1
- Require sphinx >= 5.1.1: Problems with sphinx 5.0 and 5.1.0 are
fixed. Therefore require the new version 5.1.1
- Update conf.py
- use searchbox on top of the sidelinks
- split index page
- change permalink icon
Change-Id: I0ff250e3a14e2902a3b197545643e93c633bc5ef
---
M docs/conf.py
M docs/requirements-py3.txt
2 files changed, 41 insertions(+), 25 deletions(-)
Approvals:
jenkins-bot: Verified
Xqt: Looks good to me, approved
diff --git a/docs/conf.py b/docs/conf.py
index b42b661..e1f2037 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -27,8 +27,8 @@
from os.path import abspath, dirname, join
-# Deprecated classes will generate warnings as Sphinx processes them. Ignoring
-# them.
+# Deprecated classes will generate warnings as Sphinx processes them.
+# Ignoring them.
warnings.simplefilter(action='ignore', category=FutureWarning)
@@ -45,7 +45,7 @@
# If your documentation needs a minimal Sphinx version, state it here.
#
-needs_sphinx = '4.5'
+needs_sphinx = '5.1.1'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -53,15 +53,14 @@
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosectionlabel',
+ 'sphinx.ext.autosummary',
'sphinx.ext.extlinks',
+ # 'sphinx.ext.intersphinx',
+ 'sphinx.ext.napoleon',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
- 'sphinx.ext.autosummary',
- 'sphinx.ext.napoleon',
]
-# Allow lines like "Example:" to be followed by a code block
-napoleon_use_admonition_for_examples = True
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -69,19 +68,20 @@
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
-source_suffix = ['.rst', '.md']
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
# The encoding of source files.
#
# source_encoding = 'utf-8-sig'
# The master toctree document.
-master_doc = 'index'
+root_doc = 'index'
# General information about the project.
project = pywikibot.__name__.title()
project_copyright = pywikibot.__copyright__ # alias since Python 3.5
-# author = 'test'
+author = 'Pywikibot Team'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -97,7 +97,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 = 'en'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
@@ -116,7 +116,7 @@
# The reST default role (used for this markup: `text`) to use for all
# documents.
#
-default_role = 'code'
+default_role = 'py:obj'
# If true, '()' will be appended to :func: etc. cross-reference text.
#
@@ -142,7 +142,7 @@
# keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
-# todo_include_todos = False
+todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
@@ -184,7 +184,7 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin
"default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
@@ -200,7 +200,11 @@
# Custom sidebar templates, maps document names to template names.
#
-# html_sidebars = {}
+html_sidebars = {
+ '**': [
+ 'searchbox.html', 'localtoc.html', 'relations.html',
'sourcelink.html',
+ ]
+}
# Additional templates that should be rendered to pages, maps page names to
# template names.
@@ -217,7 +221,7 @@
# If true, the index is split into individual pages for each letter.
#
-# html_split_index = False
+html_split_index = True
# If true, links to the reST sources are added to the pages.
#
@@ -259,7 +263,7 @@
# html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
-htmlhelp_basename = 'Pywikibotdoc'
+htmlhelp_basename = project + release.replace('.', '')
# -- Options for LaTeX output ---------------------------------------------
@@ -285,8 +289,8 @@
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- ('index', 'Pywikibot.tex', 'Pywikibot Documentation',
- 'Pywikibot team', 'manual'),
+ (root_doc, 'Pywikibot.tex', 'Pywikibot Documentation',
+ author, 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
@@ -316,8 +320,8 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'pywikibot', 'Pywikibot Documentation',
- ['Pywikibot team'], 1)
+ (root_doc, project, 'Pywikibot Documentation',
+ [author], 1)
]
manpages_url = 'https://www.mediawiki.org/wiki/Manual:Pywikibot/{path}'
@@ -332,8 +336,8 @@
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('index', 'Pywikibot', 'Pywikibot Documentation',
- 'Pywikibot team', 'Pywikibot', 'One line description of
project.',
+ (root_doc, project, 'Pywikibot Documentation',
+ author, project, 'One line description of project.',
'Miscellaneous'),
]
@@ -353,13 +357,25 @@
#
# texinfo_no_detailmenu = False
+# If false, do not generate in manual @ref nodes.
+#
+# texinfo_cross_references = False
+
+numfig = True
+
# Other settings
+
autodoc_typehints = 'description'
+# Allow lines like "Example:" to be followed by a code block
+napoleon_use_admonition_for_examples = True
+python_use_unqualified_type_names = True
+
# Pywikibot theme style
-html_static_path = ['_static']
+html_permalinks_icon = '#'
html_style = 'css/pywikibot.css'
+
extlinks = {
# MediaWiki API
'api': ('https://www.mediawiki.org/wiki/API:%s', 'API:%s'),
diff --git a/docs/requirements-py3.txt b/docs/requirements-py3.txt
index 7c9fd27..9da69c9 100644
--- a/docs/requirements-py3.txt
+++ b/docs/requirements-py3.txt
@@ -1,4 +1,4 @@
# This is a PIP requirements file for building Sphinx documentation of pywikibot
# requirements.txt is also needed
-sphinx == 4.5.0
\ No newline at end of file
+sphinx >= 5.1.1
\ No newline at end of file
--
To view, visit
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/818531
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: I0ff250e3a14e2902a3b197545643e93c633bc5ef
Gerrit-Change-Number: 818531
Gerrit-PatchSet: 2
Gerrit-Owner: Xqt <info(a)gno.de>
Gerrit-Reviewer: Xqt <info(a)gno.de>
Gerrit-Reviewer: jenkins-bot
Gerrit-MessageType: merged