jenkins-bot has submitted this change. (
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1170697?usp=email )
Change subject: doc: Refactor formatting of option lists in script docstrings
......................................................................
doc: Refactor formatting of option lists in script docstrings
Enhance the pywikibot_script_docstring_fixups() hook to format script
docstrings more reliably:
- Use newlines list to collect the lines
- Detect and wrap colon-containing options with :kbd:`...`
- Preserve and indent associated descriptions as definition list entries
- Always add blank lines after such entries to satisfy docutils
This avoids layout issues and reduces spurious warnings during doc builds.
Also
- update tomlib; Python 3.11 is required for sphinx 8.2
- update some scripts documentation
- add tomllib to isort standard library list
Bug: T400000
Change-Id: I191427571e40b64c81351fb73c1dddfb496a29cc
---
M docs/conf.py
M docs/requirements.txt
M pyproject.toml
M scripts/create_isbn_edition.py
M scripts/djvutext.py
M scripts/listpages.py
6 files changed, 107 insertions(+), 91 deletions(-)
Approvals:
jenkins-bot: Verified
Xqt: Looks good to me, approved
diff --git a/docs/conf.py b/docs/conf.py
index 1da84b8..e3b086d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -24,16 +24,12 @@
import os
import re
import sys
+import tomllib
import warnings
+from itertools import pairwise
from pathlib import Path
-try:
- import tomllib
-except ImportError:
- import tomli as tomllib
-
-
# Deprecated classes will generate warnings as Sphinx processes them.
# Ignoring them.
@@ -529,55 +525,75 @@
def pywikibot_script_docstring_fixups(app, what, name, obj, options,
lines) -> None:
- """Pywikibot specific conversions."""
+ """Pywikibot-specific docstring conversions for scripts."""
from scripts.cosmetic_changes import warning
if what != 'module' or 'scripts.' not in name:
return
- length = 0
- desc = ''
- for index, line in enumerate(lines):
- # highlight the first line
- if index == 0: # highlight the first line
- lines[0] = f"**{line.strip('.')}**"
+ if not lines:
+ return
+ nextline = None
+
+ # highlight the first line
+ newlines = [f"**{lines[0].strip('.')}**"]
+
+ for previous, line in pairwise(lines):
# add link for pagegenerators options
- elif line == '¶ms;':
- lines[index] = ('This script supports use of '
- ':py:mod:`pagegenerators` arguments.')
+ if line == '¶ms;':
+ newlines.append(
+ 'This script supports use of :mod:`pagegenerators` arguments.')
+ continue
# add link for fixes
- elif name == 'scripts.replace' and line == '&fixes-help;':
- lines[index] = (' The available fixes are listed '
- 'in :py:mod:`pywikibot.fixes`.')
+ if name == 'scripts.replace' and line == '&fixes-help;':
+ newlines.append(' The available fixes are '
+ 'listed in :mod:`pywikibot.fixes`.')
+ continue
# replace cosmetic changes warning
- elif name == 'scripts.cosmetic_changes' and line == '&warning;':
- lines[index] = warning
+ if name == 'scripts.cosmetic_changes' and line == '&warning;':
+ newlines.append(warning)
+ continue
# adjust options: if the option contains a colon, convert it to a
# definition list and mark the option with a :kbd: role. Also convert
# option types enclosed in square brackets to italic style.
if line.startswith('-'):
# extract term and wrap it with :kbd: role
- match = re.fullmatch(r'(-\w.+?[^ ])( {2,})(.+)', line)
+ match = re.fullmatch(r'(-\w\S+)(?:( {2,})(.+))?', line)
if match:
opt, sp, desc = match.groups()
- desc = re.sub(r'\[(float|int|str)\]', r'*(\1)*', desc)
- if ':' in opt or ' ' in opt and ', ' not in opt:
+ sp = sp or ''
+ desc = desc or ''
+ # make [type] italic
+ types = '(?:float|int|str)'
+ desc = re.sub(rf'\[({types}(?:\|{types})*)\]', r'*(\1)*', desc)
+ show_as_kbd = ':' in opt or (' ' in opt and ', ' not in opt)
+ if show_as_kbd:
+ # extract term and wrap it with :kbd: role
+ if previous:
+ # add an empty line if previous is not empty
+ newlines.append('')
length = len(opt + sp)
- lines[index] = f':kbd:`{opt}`'
+ newlines.append(f':kbd:`{opt}`')
+ # add the description to a new line later
+ if desc:
+ nextline = length, desc
else:
- lines[index] = f'{opt}{sp}{desc}'
+ newlines.append(f'{opt}{sp}{desc}')
+ continue
- elif length and (not line or line.startswith(' ' * length)):
- # Add descriptions to the next line
- lines[index] = ' ' * length + f'{desc} {line.strip()}'
- length = 0
- elif line:
- # Reset length
- length = 0
+ if nextline:
+ spaces = len(line) - len(line.lstrip()) or nextline[0]
+ newlines.append(' ' * spaces + nextline[1])
+ nextline = None
+
+ newlines.append(line)
+
+ # Overwrite original lines in-place for autodoc
+ lines[:] = newlines
def setup(app) -> None:
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 1a29bd5..3f42299 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,5 +6,4 @@
sphinxext-opengraph >= 0.9.1
sphinx-copybutton >= 0.5.2
sphinx-tabs >= 3.4.7
-tomli >= 2.2.1; python_version < '3.11'
furo >= 2024.8.6
diff --git a/pyproject.toml b/pyproject.toml
index 4520211..9ac0583 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -173,6 +173,7 @@
lines_after_imports = 2
multi_line_output = 3
use_parentheses = true
+extra_standard_library = ["tomllib"]
[tool.mypy]
diff --git a/scripts/create_isbn_edition.py b/scripts/create_isbn_edition.py
index 98bd02d..684d4f4 100755
--- a/scripts/create_isbn_edition.py
+++ b/scripts/create_isbn_edition.py
@@ -673,7 +673,7 @@
always appended.
.. seealso::
- - :wiki:`List_of_ISO_639-1_codes
+ - :wiki:`List_of_ISO_639-1_codes`
:Return: List of ISO 639-1 language codes with strings delimited by
':'.
diff --git a/scripts/djvutext.py b/scripts/djvutext.py
index ac9f640..845520e 100755
--- a/scripts/djvutext.py
+++ b/scripts/djvutext.py
@@ -1,43 +1,41 @@
#!/usr/bin/env python3
-"""This bot uploads text from djvu files onto pages in the "Page" namespace.
+"""This bot uploads text from DjVu files onto pages in the "Page" namespace.
-.. note:: It is intended to be used for Wikisource.
+.. note:: This script is intended to be used for Wikisource.
-The following parameters are supported:
+The following command-line parameters are supported:
--index: name of the index page (without the Index: prefix)
+-index: Name of the index page (without the "Index:" prefix).
--djvu: path to the djvu file, it shall be:
+-djvu: Path to the DjVu file. It can be one of the following:
- .. hlist::
+ * A path to a file
+ * A directory containing a DjVu file with the same name as
+ the index page (optional; defaults to current directory ".")
- * path to a file name
- * dir where a djvu file name as index is located optional,
- by default is current dir '.'
+-pages:<start>-<end>,...<start>-<end>,<start>-<end>
+ Page range(s) to upload (optional). Default: :samp:`start=1`,
+ :samp:`end={DjVu file number of images}`. Page ranges can be
+ specified as::
--pages:<start>-<end>,...<start>-<end>,<start>-<end> Page range to
- upload; optional, :samp:`start=1`,
- :samp:`end={djvu file number of images}`. Page ranges can be
- specified as::
+ A-B -> pages A through B
+ A- -> pages A through the end
+ A -> only page A
+ -B -> pages 1 through B
- A-B -> pages A until B
- A- -> pages A until number of images
- A -> just page A
- -B -> pages 1 until B
+This script is a subclass of :class:`ConfigParserBot<bot.ConfigParserBot>`.
+The following options can be set in a settings file (default:
+``scripts.ini``):
-This script is a :class:`ConfigParserBot <bot.ConfigParserBot>`. The
-following options can be set within a settings file which is scripts.ini
-by default:
+-summary: [str] Custom edit summary. Use quotes if the summary
+ contains spaces.
--summary: [str] Custom edit summary. Use quotes if edit summary
- contains spaces.
+-force Overwrite existing text. Optional. Default: False.
--force Overwrites existing text optional, default False.
-
--always Do not bother asking to confirm any of the changes.
+-always Do not prompt for confirmation before making changes.
"""
#
-# (C) Pywikibot team, 2008-2024
+# (C) Pywikibot team, 2008-2025
#
# Distributed under the terms of the MIT license.
#
diff --git a/scripts/listpages.py b/scripts/listpages.py
index 5226ae6..c03c209 100755
--- a/scripts/listpages.py
+++ b/scripts/listpages.py
@@ -6,64 +6,66 @@
These parameters are supported to specify which pages titles to print:
--format Defines the output format.
+-format [int|str] Defines the output format.
Can be a custom string according to python string.format()
- notation or can be selected by a number from following list
- (1 is default format):
+ notation or can be selected by a number from the following
+ list (1 is default format):
- 1 - '{num:4d} {page.title}'
- --> 10 PageTitle
+ ``1 - '{num:4d} {page.title}'``
+ → 10 PageTitle
- 2 - '{num:4d} [[{page.title}]]'
- --> 10 [[PageTitle]]
+ ``2 - '{num:4d} [[{page.title}]]'``
+ → 10 [[PageTitle]]
- 3 - '{page.title}'
- --> PageTitle
+ ``3 - '{page.title}'``
+ → PageTitle
- 4 - '[[{page.title}]]'
- --> [[PageTitle]]
+ ``4 - '[[{page.title}]]'``
+ → [[PageTitle]]
- 5 - '{num:4d} <<lightred>>{page.loc_title:<40}<<default>>'
- --> 10 localised_Namespace:PageTitle (colorised in lightred)
+ ``5 - '{num:4d} <<lightred>>{page.loc_title:<40}<<default>>'``
+ → 10 localised_Namespace:PageTitle (colorised in lightred)
- 6 - '{num:4d} {page.loc_title:<40} {page.can_title:<40}'
- --> 10 localised_Namespace:PageTitle
- canonical_Namespace:PageTitle
+ ``6 - '{num:4d} {page.loc_title:<40} {page.can_title:<40}'``
+ → 10 localised_Namespace:PageTitle
+ canonical_Namespace:PageTitle
- 7 - '{num:4d} {page.loc_title:<40} {page.trs_title:<40}'
- --> 10 localised_Namespace:PageTitle
- outputlang_Namespace:PageTitle
- (*) requires "outputlang:lang" set.
+ ``7 - '{num:4d} {page.loc_title:<40} {page.trs_title:<40}'``
+ → 10 localised_Namespace:PageTitle
+ outputlang_Namespace:PageTitle
- num is the sequential number of the listed page.
+ .. important:: Requires ``outputlang:lang`` set, see
+ below.
- An empty format is equal to ``-notitle`` and just shows the
- total amount of pages.
+ ``num`` is the sequential number of the listed page.
+
+ .. hint:: An empty format is equal to ``-notitle`` and just
+ shows the total number of pages.
-outputlang
- Language for translation of namespaces.
+ [str] Language for translation of namespaces.
-notitle Page title is not printed.
-get Page content is printed.
--tofile Save Page titles to a single file. File name can be set
- with -tofile:filename or -tofile:dir_name/filename.
+-tofile [str] Save Page titles to a single file. File name can be
+ set with ``-tofile:filename`` or ``-tofile:dir_name/filename``.
-save Save Page content to a file named as
:code:`page.title(as_filename=True)`. Directory can be set
with ``-save:dir_name``. If no dir is specified, current
directory will be used.
--encode File encoding can be specified with '-encode:name' (name
- must be a valid python encoding: utf-8, etc.). If not
+-encode [str] File encoding can be specified with ``-encode:name``
+ (name must be a valid python encoding: utf-8, etc.). If not
specified, it defaults to :code:`config.textfile_encoding`.
-put: [str] Save the list to the defined page of the wiki. By
default it does not overwrite an existing page.
--overwrite Overwrite the page if it exists. Can only by applied with
+-overwrite Overwrite the page if it exists. Can only be applied with
-put.
-summary: [str] The summary text when the page is written. If it's one
@@ -99,7 +101,7 @@
¶ms;
"""
#
-# (C) Pywikibot team, 2008-2024
+# (C) Pywikibot team, 2008-2025
#
# Distributed under the terms of the MIT license.
#
--
To view, visit
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1170697?usp=email
To unsubscribe, or for help writing mail filters, visit
https://gerrit.wikimedia.org/r/settings?usp=email
Gerrit-MessageType: merged
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Change-Id: I191427571e40b64c81351fb73c1dddfb496a29cc
Gerrit-Change-Number: 1170697
Gerrit-PatchSet: 6
Gerrit-Owner: Xqt <[email protected]>
Gerrit-Reviewer: Xqt <[email protected]>
Gerrit-Reviewer: jenkins-bot
_______________________________________________
Pywikibot-commits mailing list -- [email protected]
To unsubscribe send an email to [email protected]
