[doc] Update scripts description for add_text.py and clean_sandbox.py

Add type hints to options

Change-Id: I63e21dd1ad91dd2b03f7f061c5af5885519a56b5

docs/conf.py

@@ -534,7 +534,7 @@ def pywikibot_script_docstring_fixups(app, what, name, obj, options, lines):
     from scripts.cosmetic_changes import warning
 
     # these scripts are skipped for fixing options lists
-    skipscripts = {'add_text'}
+    skipscripts = {'add_text', 'clean_sandbox'}
 
     if what != 'module':
         return
@@ -590,6 +590,19 @@ def pywikibot_script_docstring_fixups(app, what, name, obj, options, lines):
             length = 0
 
 
+TYPE_PATTERN = re.compile(r'(  +)\[(float|int|str)\]')
+
+
+def pywikibot_option_types_fixups(app, what, name, obj, options, lines):
+    """Convert option types enclosed in square brackets to italic style."""
+    if what != 'module' or 'scripts.' not in name:
+        return
+
+    for index, line in enumerate(lines):
+        if line.startswith('-'):
+            lines[index] = TYPE_PATTERN.sub(r'\1*(\2)*', line)
+
+
 def pywikibot_family_classproperty_getattr(obj, name, *defargs):
     """Custom getattr() to get classproperty instances."""
     from sphinx.util.inspect import safe_getattr
@@ -618,6 +631,7 @@ def setup(app):
     """Implicit Sphinx extension hook."""
     app.connect('autodoc-process-docstring', pywikibot_docstring_fixups)
     app.connect('autodoc-process-docstring', pywikibot_script_docstring_fixups)
+    app.connect('autodoc-process-docstring', pywikibot_option_types_fixups)
     app.add_autodoc_attrgetter(type, pywikibot_family_classproperty_getattr)
 
 

scripts/add_text.py

@@ -6,11 +6,11 @@
 
 Use the following command line parameters to specify what to add:
 
--text        Text to append. "\n" are interpreted as newlines.
+-text        [str] Text to append. "\n" are interpreted as newlines.
 
--textfile    Path to a file with text to append
+-textfile    [str] Path to a file with text to append
 
--summary     Change summary to use
+-summary     [str] Change summary to use
 
 -up          Append text to the top of the page rather than the bottom
 
@@ -28,7 +28,7 @@
 -talk, -talkpage
              Put the text onto the talk page instead
 
--excepturl   Skip pages with a url that matches this regular expression
+-excepturl   [str] Skip pages with a url that matches this regular expression
 
 -noreorder   Place the text beneath the categories and interwiki
 

scripts/clean_sandbox.py

@@ -1,46 +1,48 @@
 #!/usr/bin/env python3
-"""
-This bot resets a (user) sandbox with predefined text.
+"""This bot resets a (user) sandbox with predefined text.
 
 This script understands the following command-line arguments:
 
 &params;
 
 Furthermore, the following command line parameters are supported:
 
-    -hours:#       Use this parameter if to make the script repeat itself
-                   after # hours. Hours can be defined as a decimal. 0.01
-                   hours are 36 seconds; 0.1 are 6 minutes.
+-hours     [float] Use this parameter if to make the script repeat
+           itself after the given hours. Hours can be defined as a
+           decimal. 0.01 hours are 36 seconds; 0.1 are 6 minutes.
 
-    -delay:#       Use this parameter for a wait time after the last edit
-                   was made. If no parameter is given it takes it from
-                   hours and limits it between 5 and 15 minutes.
-                   The minimum delay time is 5 minutes.
+-delay     [int] Use this parameter for a wait time after the last edit
+           was made. If no parameter is given it takes it from hours and
+           limits it between 5 and 15 minutes. The minimum delay time is
+           5 minutes.
 
-    -text          The text that substitutes in the sandbox, you can use this
-                   when you haven't configured clean_sandbox for your wiki.
+-text      [str] The text that substitutes in the sandbox, you can use
+           this when you haven't configured clean_sandbox for your wiki.
 
-    -textfile      As an alternative to -text, you can use this to provide
-                   a file containing the text to be used.
+-textfile  [str] As an alternative to -text, you can use this to provide
+           a file containing the text to be used.
 
-    -summary       Summary of the edit made by the bot. Overrides the default
-                   from i18n.
+-summary   [str] Summary of the edit made by the bot. Overrides the
+           default from i18n.
 
 This script is a :py:obj:`ConfigParserBot <bot.ConfigParserBot>`.
 All local parameters can be given inside a scripts.ini file. Options
 passed to the script are priorized over options read from ini file.
 
+For example:
+
+.. code:: ini
+
+   [clean_sandbox]
+   # the parameter section for clean_sandbox script
+   summary = Bot: Cleaning sandbox
+   text = {{subst:Clean Sandbox}}
+   hours: 0.5
+   delay: 7
+
 .. seealso:: :python:`Supported .ini File Structure
    <library/configparser.html#supported-ini-file-structure>`
 
-For example:
-
-    [clean_sandbox]
-    # the parameter section for clean_sandbox script
-    summary = Bot: Cleaning sandbox
-    text = {{subst:Clean Sandbox}}
-    hours: 0.5
-    delay: 7
 """
 #
 # (C) Pywikibot team, 2006-2024