jenkins-bot submitted this change.

View Change

[doc] Add the library usage to the documentation

Also require sphinx 3.5+ due to auto indentation

Depends-On: I8c9a92adf4be4b29f69ee3723ab81054328be351
Change-Id: Ic0fd512b442833b2807fea6fc47fa7c9a5306073
---
M docs/library_usage.rst
M docs/requirements-py3.txt
2 files changed, 85 insertions(+), 2 deletions(-)

diff --git a/docs/library_usage.rst b/docs/library_usage.rst
index 36ef39a..95da419 100644
--- a/docs/library_usage.rst
+++ b/docs/library_usage.rst
@@ -1,5 +1,88 @@
 Using pywikibot as library
 --------------------------
 
+Pywikibot provides bot classes to develop your own script easily. Here 
+is a minimal example script which shows their usage:
+
+..  code-block:: python
+    :linenos:
+    :emphasize-lines: 5,12,18
+
+    import pywikibot
+    from pywikibot import pagegenerators
+    from pywikibot.bot import ExistingPageBot
+
+    class MyBot(ExistingPageBot):
+
+        update_options = {
+            'text': 'This is a test text',
+            'summary': 'Bot: a bot test edit with Pywikbot.',
+        }
+
+        def treat_page(self):
+            """Load the given page, do some changes, and save it."""
+            text = self.current_page.text
+            text += '\n' + self.opt.text
+            self.put_current(text, summary=self.opt.summary)
+
+    def main():
+        """Parse command line arguments and invoke bot."""
+        options = {}
+        gen_factory = pagegenerators.GeneratorFactory()
+        # Option parsing
+        local_args = pywikibot.handle_args(args)  # global options
+        local_args = gen_factory.handle_args(local_args)  # generators options
+        for arg in local_args:
+            opt, sep, value = arg.partition(':')
+            if opt in ('-summary', '-text'):
+                options[opt[1:]] = value
+        MyBot(generator=gen_factory.getCombinedGenerator(), **options).run()
+
+    if __name == '__main__':
+        main()
+        
+The script can be invoked from commandline like::
+
+    python mybot -site:wikipedia:test -page:Sandbox -text:"A text added to the sandbox"
+    
+**Explanations:**
+
+:1-3: Import necessary framework code parts
+:5:   The bot is derived from ExistingPageBot. All pages from generator 
+      which does not exists are skipped.
+:7:   Every Bot has an *always* option which autoconfirms any changes if
+      set to True. To expand all available options of a bot and set the
+      default values of them, use `update_options` attribute or update
+      `available_options` like it is shown in BasicBot below. 
+:12:  All changes for each page are made in this method.
+:14:  `currentpage` is the current :py:obj:`pywikibot.Page` object from
+      generator.
+:15:  All bot options which are passed to the bot class when 
+      instantiating it are accessable via opt attribute. `opt.always`, 
+      `opt.text` and `opt.summary` are all available options for this
+      bot class.
+:16:  Save the changes to the live wiki.
+:18:  Parse command line options inside this function.
+:20:  A dict which holds all options for the bot.
+:21:  :py:obj:`pywikibot.pagegenerators.GeneratorFactory` supports
+      generators and filter options.
+:23:  Pywikibot provides global options like site specification or
+      a simulate switch to prevent live wiki changes.
+:24:  Generators and filter options of :py:obj:`pywikibot.pagegenerators`
+      are parsed here.
+:25:  Local options which are are available for the current bot are
+      parsed in this loop.
+:29:  Create the bot passing keyword only parameters and run it.
+
+Basic script
+~~~~~~~~~~~~
+
+:py:obj:`scripts.basic` is a more advanced sample script and shipped
+with the scripts folder. Here is the content:
+
+.. literalinclude:: ../scripts/basic.py
+   :language: python
+
 .. note::
-   Please see the documentation at `Manual:Pywikibot/Create your own script <https://www.mediawiki.org/wiki/Manual:Pywikibot/Create_your_own_script>`_
+   Please also see the documentation at
+   `Manual:Pywikibot/Create your own script <https://www.mediawiki.org/wiki/Manual:Pywikibot/Create_your_own_script>`_
diff --git a/docs/requirements-py3.txt b/docs/requirements-py3.txt
index d455bf2..f6022b4 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 >= 1.8, != 3.1.0, != 3.5.0, != 4.0.0
\ No newline at end of file
+sphinx > 3.5.0, != 4.0.0
\ No newline at end of file

To view, visit change 699760. To unsubscribe, or for help writing mail filters, visit settings.