[IMPR] add transwikiimort script to documentation

Change-Id: Ie262d83a78a19e64e79a58a9301bde392258c751
---
M docs/conf.py
M docs/scripts/auxiliary.rst
M docs/scripts_ref/scripts.rst
M scripts/transwikiimport.py
4 files changed, 71 insertions(+), 47 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index d6d1a17..786fecc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -466,8 +466,12 @@
 suppress_warnings = ['autosectionlabel.*']
 toc_object_entries_show_parents = 'hide'
 
-# Allow lines like "Example:" to be followed by a code block
+# Napoleon settings
 napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = True
+napoleon_custom_sections = ['Advice', 'Advices', 'Hints', 'Rights', 'Tips']
+
 python_use_unqualified_type_names = True
 modindex_common_prefix = ['pywikibot.scripts.']
 
diff --git a/docs/scripts/auxiliary.rst b/docs/scripts/auxiliary.rst
index e4874ca..061362b 100644
--- a/docs/scripts/auxiliary.rst
+++ b/docs/scripts/auxiliary.rst
@@ -22,3 +22,10 @@
 .. automodule:: scripts.transferbot
    :no-members:
    :noindex:
+
+transwikiimport script
+======================
+
+.. automodule:: scripts.transwikiimport
+   :no-members:
+   :noindex:
diff --git a/docs/scripts_ref/scripts.rst b/docs/scripts_ref/scripts.rst
index 001b818..977a844 100644
--- a/docs/scripts_ref/scripts.rst
+++ b/docs/scripts_ref/scripts.rst
@@ -254,6 +254,11 @@
 
 .. automodule:: scripts.transferbot
 
+transwikiimport script
+======================
+
+.. automodule:: scripts.transwikiimport
+
 unusedfiles script
 ==================
 
diff --git a/scripts/transwikiimport.py b/scripts/transwikiimport.py
index 44135b6..aa531fe 100755
--- a/scripts/transwikiimport.py
+++ b/scripts/transwikiimport.py
@@ -45,96 +45,95 @@
 prefix:
 
     python pwb.py transwikiimport -interwikisource:en -cat:"Query service" \
-        -prefix:"Wikipedia:Import enwp/" -fullhistory -assignknownusers
+-prefix:"Wikipedia:Import enwp/" -fullhistory -assignknownusers
 
 Copy the template "Query service" from the English Wikipedia to the home
 Wiktionary:
 
     python pwb.py transferbot -interwikisource:w:en \
-        -page:"Template:Query service" -fullhistory -assignknownusers
+-page:"Template:Query service" -fullhistory -assignknownusers
 
 Copy 10 wanted templates of the home Wikipedia from English Wikipedia to
-the home Wikipedia
+the home Wikipedia:
 
-    python pwb.py transferbot -interwikisource:en \
-        -wantedtemplates:10 -target -fullhistory -assignknownusers
+    python pwb.py transferbot -interwikisource:en -wantedtemplates:10 \
+-target -fullhistory -assignknownusers
+
 
 Advices
 -------
 
-The module gives access to all parameters of the API (and specialpage)
-    and is compatible to the transferbot module.
-However for most scenarios the following parameters should be avoided:
-  -overwrite (by default set as False)
-  -target (by default set as False)
-  -includealltemplates (by default set as False)
+The module gives access to all parameters of the API (and special page)
+and is compatible to the :mod:`scripts.transferbot` script.
+However for most scenarios the parameters ``-overwrite``, ``-target`` and
+``-includealltemplates`` should be avoided; by default they are set to
+False.
 
-The correspondingnamespace is used only if the namespaces on both wikis do not
-    correspond one with another.
+The correspondingnamespace is used only if the namespaces on both wikis
+do not correspond one with another.
 
 Correspondingnamespace and rootpage are mutually exclusive.
 
-Target and rootpage are mutually exclusive.
-    (This combination does not seem to be feasible.)
+Target and rootpage are mutually exclusive. (This combination does not
+seem to be feasible.)
 
 If the target page already exists, the target page will be overwritten
-    if -overwrite is set or skipped otherwise.
+if ``-overwrite`` is set or skipped otherwise.
 
 The list of pages to be imported can be generated outside of the pywikbot:
 
-    for i in {1..10} ; do python3 pwb.py transwikiimport -interwikisource:mul \
--page:"Page:How to become famous.djvu/$i" -fullhistory \
--assignknownusers ; done
+    for i in {1..10} ; do python3 pwb.py transwikiimport \
+-interwikisource:mul -page:"Page:How to become famous.djvu/$i" \
+-fullhistory -assignknownusers ; done
 
-(The pages Page:How to become famous.djvu/1, Page:How to become famous.djvu/2 \
-.. Page:How to become famous.djvu/10 will be copied
-    from wikisource (mul) to the home-wikisource, all versions will be imported
-    and the usernames will be identified
-    (existing pages will be skipped.)
+*The pages *``Page:How to become famous.djvu/1``*,
+*``Page:How to become famous.djvu/2``* ..
+*``Page:How to become famous.djvu/10``* will be copied from wikisource
+(mul) to the home-wikisource, all versions will be imported and the
+usernames will be identified (existing pages will be skipped).*
 
 Or generated using the usual pywikibot generators:
 
     python3 pwb.py transwikiimport -interwikisource:mul \
--prefixindex:"Page:How to become famous.djvu" \
--fullhistory -assignknownusers \
--summary:"Book copied from oldwiki."
+-prefixindex:"Page:How to become famous.djvu" -fullhistory \
+-assignknownusers -summary:"Book copied from oldwiki."
 
-(All pages like Page:How to become famous.djvu... will be copied
-    from wikisource (mul) to the home-wikisource, all versions will be
-    imported and the usernames will be identified
-    (existing pages will be skipped.)
+*All pages like *``Page:How to become famous.djvu``*... will be copied
+from wikisource (mul) to the home-wikisource, all versions will be
+imported and the usernames will be identified (existing pages will be
+skipped).*
 
-The global option -simulate disables the import and the bot prints the
-names of the pages that would be imported. Since the import of pages is
-a quite exceptionell process and potentially dangerous it should be made
-carefully and tested in advance.
+The global option ``-simulate`` disables the import and the bot prints
+the names of the pages that would be imported. Since the import of pages
+is a quite exceptionell process and potentially dangerous it should be
+made carefully and tested in advance.
 
-The -simulate option can help to find out which pages would be moved
+The ``-simulate`` option can help to find out which pages would be moved
 and what would be the target of the import. However it does not print
 the titles of the transcluded pages (e.g. templates) if
--includealltemplates is set.
+``-includealltemplates`` is set.
 
 This option is quite *dangerous*. If the title of an existing page on
 home wiki clashes with the title of one of the linked pages it would be
 *overritten*. The histories would be merged. (If the imported version is
-newer.) Even if -overwrite is not set the linked page *can be
+newer.) Even if ``-overwrite`` is not set the linked page *can be
 overwritten*.
 
 
-Interwikisource
----------------
+Hints
+-----
 
-The list of wikis that can be used as a source
-    is defined in the variable $wgImportSources
-It can be viewed on the Specialpage:Import.
+The list of wikis that can be used as a interwiki source is defined in
+the variable ``$wgImportSources``. It can be viewed on the
+``Special:Import`` page.
 
 
 Rights
 ------
 
-For tranwikiimport (and even to access the Specialpage:Import)
-    the appropriate flag on the account
-    must be set (usually administrator, tranwiki importer or importer).
+For transwikiimport script and even to access the ``Special:Import``
+page the appropriate flag on the account must be set, usually
+administrator, transwiki importer or importer.
 
 .. versionadded:: 8.2
 """

