[doc] Add admoniton and hint for pywikibot.handle_args() usage

Bug: T359766
Change-Id: Idf3d76406590dd0a39cc08dd47c39d45c6b32c60
---
M pywikibot/bot.py
M pywikibot/scripts/wrapper.py
2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/pywikibot/bot.py b/pywikibot/bot.py
index 04606a0..935886d 100644
--- a/pywikibot/bot.py
+++ b/pywikibot/bot.py
@@ -672,6 +672,26 @@
     ['-myoption']
     >>> for arg in local_args: pass  # do whatever is wanted with local_args
 
+    .. caution::
+       Global options might be introduced without warning period. It is
+       up to developers to verify that global options do not interfere
+       with local script options of private scripts.
+
+    .. tip::
+       Avoid using this method in your private scripts and use the
+       :mod:`pwb<pywikibot.scripts.wrapper>` wrapper instead. In
+       directory mode::
+
+           python pwb.py <global options> <name_of_script> <local options>
+
+       With installed site package::
+
+           pwb <global options> <name_of_script> <local options>
+
+       .. note:: the :mod:`pwb<pywikibot.scripts.wrapper>` wrapper can
+          be used even if the `handle_args` method is used within the
+          script.
+
     .. versionchanged:: 5.2
        *-site* global option was added
     .. versionchanged:: 7.1
diff --git a/pywikibot/scripts/wrapper.py b/pywikibot/scripts/wrapper.py
index ba63b8d..32eaa8f 100755
--- a/pywikibot/scripts/wrapper.py
+++ b/pywikibot/scripts/wrapper.py
@@ -30,12 +30,14 @@
 
     python pwb.py -lang:de bot_tests -v
 
+.. seealso:: :mod:`pwb` entry point
 .. versionchanged:: 7.0
-   pwb wrapper was added to the Python site package lib
+   pwb wrapper was added to the Python site package lib.
 .. versionchanged:: 7.7
-   pwb wrapper is able to set ``PYWIKIBOT_TEST_...`` environment variables
+   pwb wrapper is able to set ``PYWIKIBOT_TEST_...`` environment variables,
+   see :ref:`Environment variables`.
 .. versionchanged:: 8.0
-   renamed to wrapper.py
+   renamed to wrapper.py.
 """
 #
 # (C) Pywikibot team, 2012-2024

