[doc] user options list with add_text script

Change-Id: Iddffefc4ba9b9510a4ff040037e293ce7b2f7220

docs/conf.py

@@ -44,6 +44,7 @@
 
 os.environ['PYWIKIBOT_NO_USER_CONFIG'] = '1'
 import pywikibot  # noqa: E402
+from pywikibot.backports import removeprefix  # noqa: E402
 
 
 # -- General configuration ------------------------------------------------
@@ -532,13 +533,17 @@ def pywikibot_script_docstring_fixups(app, what, name, obj, options, lines):
     """Pywikibot specific conversions."""
     from scripts.cosmetic_changes import warning
 
+    # these scripts are skipped for fixing options lists
+    skipscripts = {'add_text'}
+
     if what != 'module':
         return
 
     if not name.startswith('scripts.'):
         return
 
     length = 0
+    shortname = removeprefix(name, 'scripts.')
     for index, line in enumerate(lines):
         # highlight the first line
         if index == 0:  # highlight the first line
@@ -559,8 +564,10 @@ def pywikibot_script_docstring_fixups(app, what, name, obj, options, lines):
             lines[index] = warning
 
         # Initiate code block except pagegenerator arguments follows
-        elif (line.endswith(':') and not line.lstrip().startswith(':')
-                and 'Traceback (most recent call last)' not in line):
+        elif (shortname not in skipscripts
+              and line.endswith(':')
+              and not line.lstrip().startswith(':')
+              and 'Traceback (most recent call last)' not in line):
             for afterline in lines[index + 1:]:
                 if not afterline:
                     continue
@@ -569,7 +576,7 @@ def pywikibot_script_docstring_fixups(app, what, name, obj, options, lines):
                 break
 
         # adjust options
-        if line.startswith('-'):
+        if shortname not in skipscripts and line.startswith('-'):
             # Indent options
             match = re.match(r'-[^ ]+? +', line)
             if match:

scripts/add_text.py

@@ -1,35 +1,36 @@
 #!/usr/bin/env python3
-r"""
-Append text to the top or bottom of a page.
+r"""Append text to the top or bottom of a page.
 
-By default this adds the text to the bottom above the categories and interwiki.
+By default this adds the text to the bottom above the categories and
+interwiki.
 
 Use the following command line parameters to specify what to add:
 
--text             Text to append. "\n" are interpreted as newlines.
+-text        Text to append. "\n" are interpreted as newlines.
 
--textfile         Path to a file with text to append
+-textfile    Path to a file with text to append
 
--summary          Change summary to use
+-summary     Change summary to use
 
--up               Append text to the top of the page rather than the bottom
+-up          Append text to the top of the page rather than the bottom
 
--create           Create the page if necessary. Note that talk pages are
-                  created already without of this option.
+-create      Create the page if necessary. Note that talk pages are
+             created already without of this option.
 
--createonly       Only create the page but do not edit existing ones
+-createonly  Only create the page but do not edit existing ones
 
--always           If used, the bot won't ask if it should add the specified
-                  text
+-always      If used, the bot won't ask if it should add the specified
+             text
 
--major            If used, the edit will be saved without the "minor edit" flag
+-major       If used, the edit will be saved without the "minor edit"
+             flag
 
--talkpage         Put the text onto the talk page instead
--talk
+-talk, -talkpage
+             Put the text onto the talk page instead
 
--excepturl        Skip pages with a url that matches this regular expression
+-excepturl   Skip pages with a url that matches this regular expression
 
--noreorder        Place the text beneath the categories and interwiki
+-noreorder   Place the text beneath the categories and interwiki
 
 Furthermore, the following can be used to specify which pages to process...
 
@@ -40,20 +41,26 @@
 
 Append 'hello world' to the bottom of the sandbox:
 
-    python pwb.py add_text -page:Wikipedia:Sandbox \
-    -summary:"Bot: pywikibot practice" -text:"hello world"
+.. code-block:: batch
+
+   python pwb.py add_text -page:Wikipedia:Sandbox
+   -summary:"Bot: pywikibot practice" -text:"hello world"
 
 Add a template to the top of the pages with 'category:catname':
 
-    python pwb.py add_text -cat:catname -summary:"Bot: Adding a template" \
-    -text:"{{Something}}" -except:"\{\{([Tt]emplate:|)[Ss]omething" -up
+.. code-block:: batch
+
+   python pwb.py add_text -cat:catname -summary:"Bot: Adding a template"
+   -text:"{{Something}}" -except:"\{\{([Tt]emplate:|)[Ss]omething" -up
 
 Command used on it.wikipedia to put the template in the page without any
 category:
 
-    python pwb.py add_text -except:"\{\{([Tt]emplate:|)[Cc]ategorizzare" \
-    -text:"{{Categorizzare}}" -excepturl:"class='catlinks'>" -uncat \
-    -summary:"Bot: Aggiungo template Categorizzare"
+.. code-block:: batch
+
+   python pwb.py add_text -except:"\{\{([Tt]emplate:|)[Cc]ategorizzare"
+   -text:"{{Categorizzare}}" -excepturl:"class='catlinks'>" -uncat
+   -summary:"Bot: Aggiungo template Categorizzare"
 """
 #
 # (C) Pywikibot team, 2007-2024