Xqt has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/834524 )

Change subject: [doc] solve some sphinx issues ......................................................................

[doc] solve some sphinx issues

Change-Id: Ifc33521e3009dc1311cabd6adb86de1d4312e7ec --- M docs/api_ref/pywikibot.page.rst M docs/conf.py M docs/scripts/administrative.rst M docs/scripts/auxiliary.rst M docs/scripts/categories.rst M docs/scripts/general.rst M docs/scripts/global.rst M docs/scripts/images.rst M docs/scripts/main.rst M docs/scripts/maintenance.rst M docs/scripts/nonedit.rst M docs/scripts/other.rst M docs/scripts/templates.rst M docs/scripts/unsorted.rst M docs/scripts/wikibase.rst M docs/scripts_ref/scripts.maintenance.rst M docs/tests_ref/pwb.rst M pywikibot/site/_extensions.py M pywikibot/site/_generators.py M pywikibot/tools/_deprecate.py M pywikibot/tools/collections.py M scripts/category.py M scripts/replace.py M tests/archivebot_tests.py 24 files changed, 91 insertions(+), 33 deletions(-)

Approvals: Xqt: Verified; Looks good to me, approved

diff --git a/docs/api_ref/pywikibot.page.rst b/docs/api_ref/pywikibot.page.rst index 1204533..2b8a308 100644 --- a/docs/api_ref/pywikibot.page.rst +++ b/docs/api_ref/pywikibot.page.rst @@ -4,8 +4,8 @@ .. automodule:: page :synopsis: Interface of various types of MediaWiki pages

-Submodules ----------- +Page Submodules +---------------

:mod:`page._collections` Wikibase Entity Structures ---------------------------------------------------- diff --git a/docs/conf.py b/docs/conf.py index b17aabb..3aabf0c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -367,8 +367,9 @@ # Other settings show_authors = True todo_include_todos = True - autodoc_typehints = 'description' +# autosectionlabel_prefix_document = True +suppress_warnings = ['autosectionlabel.*']

# Allow lines like "Example:" to be followed by a code block napoleon_use_admonition_for_examples = True diff --git a/docs/scripts/administrative.rst b/docs/scripts/administrative.rst index 3c829fa..5d97c08 100644 --- a/docs/scripts/administrative.rst +++ b/docs/scripts/administrative.rst @@ -6,33 +6,39 @@

.. automodule:: scripts.blockpageschecker :no-members: + :noindex:

delete script description -------------------------

.. automodule:: scripts.delete :no-members: + :noindex:

patrol script description -------------------------

.. automodule:: scripts.patrol :no-members: + :noindex:

protect script description --------------------------

.. automodule:: scripts.protect :no-members: + :noindex:

revertbot script description ----------------------------

.. automodule:: scripts.revertbot :no-members: + :noindex:

speedy_delete script description ---------------------------------

.. automodule:: scripts.speedy_delete :no-members: + :noindex: diff --git a/docs/scripts/auxiliary.rst b/docs/scripts/auxiliary.rst index c24054f..afff626 100644 --- a/docs/scripts/auxiliary.rst +++ b/docs/scripts/auxiliary.rst @@ -6,15 +6,18 @@

.. automodule:: scripts.clean_sandbox :no-members: + :noindex:

cosmetic_changes script description ------------------------------------

.. automodule:: scripts.cosmetic_changes :no-members: + :noindex:

transferbot script description ------------------------------

.. automodule:: scripts.transferbot :no-members: + :noindex: diff --git a/docs/scripts/categories.rst b/docs/scripts/categories.rst index 5fa1fa0..3920f6a 100644 --- a/docs/scripts/categories.rst +++ b/docs/scripts/categories.rst @@ -6,10 +6,12 @@

.. automodule:: scripts.category_redirect :no-members: + :noindex:

commonscat script description -----------------------------

.. automodule:: scripts.commonscat :no-members: + :noindex:

diff --git a/docs/scripts/general.rst b/docs/scripts/general.rst index 93a801d..144b194 100644 --- a/docs/scripts/general.rst +++ b/docs/scripts/general.rst @@ -6,15 +6,18 @@

.. automodule:: scripts.archivebot :no-members: + :noindex:

movepages script description description ----------------------------------------

.. automodule:: scripts.movepages :no-members: + :noindex:

pagefromfile script description description -------------------------------------------

.. automodule:: scripts.pagefromfile :no-members: + :noindex: diff --git a/docs/scripts/global.rst b/docs/scripts/global.rst index 9730140..679f67d 100644 --- a/docs/scripts/global.rst +++ b/docs/scripts/global.rst @@ -8,10 +8,11 @@

.. automodule:: scripts.interwiki :no-members: - + :noindex:

redirect script description ---------------------------

.. automodule:: scripts.redirect :no-members: + :noindex: diff --git a/docs/scripts/images.rst b/docs/scripts/images.rst index d6fe32a..6340b25 100644 --- a/docs/scripts/images.rst +++ b/docs/scripts/images.rst @@ -6,39 +6,46 @@

.. automodule:: scripts.checkimages :no-members: + :noindex:

commons_information script description ---------------------------------------

.. automodule:: scripts.commons_information :no-members: + :noindex:

data_ingestion script description ----------------------------------

.. automodule:: scripts.data_ingestion :no-members: + :noindex:

image script description ------------------------

.. automodule:: scripts.image :no-members: + :noindex:

imagetransfer script description --------------------------------

.. automodule:: scripts.imagetransfer :no-members: + :noindex:

nowcommons script description -----------------------------

.. automodule:: scripts.nowcommons :no-members: + :noindex:

unusedfiles script description ------------------------------

.. automodule:: scripts.unusedfiles :no-members: + :noindex: diff --git a/docs/scripts/main.rst b/docs/scripts/main.rst index b3ad628..50170f3 100644 --- a/docs/scripts/main.rst +++ b/docs/scripts/main.rst @@ -6,33 +6,39 @@

.. automodule:: scripts.add_text :no-members: + :noindex:

category script description ---------------------------

.. automodule:: scripts.category :no-members: + :noindex:

replace script description --------------------------

.. automodule:: scripts.replace :no-members: + :noindex:

solve_disambiguation script description ----------------------------------------

.. automodule:: scripts.solve_disambiguation :no-members: + :noindex:

upload script description -------------------------

.. automodule:: scripts.upload :no-members: + :noindex:

weblinkchecker script description ---------------------------------

.. automodule:: scripts.weblinkchecker :no-members: + :noindex: diff --git a/docs/scripts/maintenance.rst b/docs/scripts/maintenance.rst index 9710629..cf64b30 100644 --- a/docs/scripts/maintenance.rst +++ b/docs/scripts/maintenance.rst @@ -6,22 +6,26 @@

.. automodule:: scripts.maintenance.cache :no-members: + :noindex:

colors script description -------------------------

.. automodule:: scripts.maintenance.colors :no-members: + :noindex:

sorting_order script description ---------------------------------

.. automodule:: scripts.maintenance.sorting_order :no-members: + :noindex:

wikimedia_sites script description -----------------------------------

.. automodule:: scripts.maintenance.wikimedia_sites :no-members: + :noindex:

diff --git a/docs/scripts/nonedit.rst b/docs/scripts/nonedit.rst index 851bb6a..a16112b 100644 --- a/docs/scripts/nonedit.rst +++ b/docs/scripts/nonedit.rst @@ -6,9 +6,11 @@

.. automodule:: scripts.listpages :no-members: + :noindex:

touch script description ------------------------

.. automodule:: scripts.touch :no-members: + :noindex: diff --git a/docs/scripts/other.rst b/docs/scripts/other.rst index f462718..f2a0089 100644 --- a/docs/scripts/other.rst +++ b/docs/scripts/other.rst @@ -6,3 +6,4 @@

.. automodule:: scripts.welcome :no-members: + :noindex: diff --git a/docs/scripts/templates.rst b/docs/scripts/templates.rst index 50d77ba..5bb8f5e 100644 --- a/docs/scripts/templates.rst +++ b/docs/scripts/templates.rst @@ -6,9 +6,11 @@

.. automodule:: scripts.template :no-members: + :noindex:

templatecount script description --------------------------------

.. automodule:: scripts.templatecount :no-members: + :noindex: diff --git a/docs/scripts/unsorted.rst b/docs/scripts/unsorted.rst index b3ef927..ee6fcbd 100644 --- a/docs/scripts/unsorted.rst +++ b/docs/scripts/unsorted.rst @@ -6,76 +6,86 @@

.. automodule:: scripts.basic :no-members: + :noindex:

change_pagelang script description -----------------------------------

.. automodule:: scripts.change_pagelang :no-members: + :noindex:

coordinate_import script description -------------------------------------

.. automodule:: scripts.coordinate_import :no-members: + :noindex:

delinker script description --------------------------- .. automodule:: scripts.delinker :no-members: + :noindex:

djvutext script description --------------------------- .. automodule:: scripts.djvutext :no-members: + :noindex:

download_dump script description ---------------------------------

.. automodule:: scripts.download_dump :no-members: + :noindex:

fixing_redirects script description ------------------------------------

.. automodule:: scripts.fixing_redirects :no-members: + :noindex:

misspelling script description ------------------------------

.. automodule:: scripts.misspelling :no-members: + :noindex:

noreferences script description -------------------------------

.. automodule:: scripts.noreferences :no-members: - + :noindex:

parser_function_count script description ------------------------------------------

.. automodule:: scripts.parser_function_count :no-members: - + :noindex:

reflinks script description ---------------------------

.. automodule:: scripts.reflinks :no-members: + :noindex:

replicate_wiki script description ----------------------------------

.. automodule:: scripts.replicate_wiki :no-members: - + :noindex:

watchlist script description ----------------------------

.. automodule:: scripts.watchlist :no-members: + :noindex: diff --git a/docs/scripts/wikibase.rst b/docs/scripts/wikibase.rst index 59e5da8..28d3965 100644 --- a/docs/scripts/wikibase.rst +++ b/docs/scripts/wikibase.rst @@ -6,39 +6,46 @@

.. automodule:: scripts.claimit :no-members: + :noindex:

create_isbn_edition script description ----------------------------------------

.. automodule:: scripts.create_isbn_edition :no-members: + :noindex:

dataextend script description -----------------------------

.. automodule:: scripts.dataextend :no-members: + :noindex:

harvest_template script description ------------------------------------

.. automodule:: scripts.harvest_template :no-members: + :noindex:

illustrate_wikidata script description ---------------------------------------

.. automodule:: scripts.illustrate_wikidata :no-members: + :noindex:

interwikidata script description --------------------------------

.. automodule:: scripts.interwikidata :no-members: + :noindex:

newitem script description --------------------------

.. automodule:: scripts.newitem :no-members: + :noindex: diff --git a/docs/scripts_ref/scripts.maintenance.rst b/docs/scripts_ref/scripts.maintenance.rst index 93770a9..112695e 100644 --- a/docs/scripts_ref/scripts.maintenance.rst +++ b/docs/scripts_ref/scripts.maintenance.rst @@ -3,8 +3,8 @@

.. automodule:: scripts.maintenance

-Submodules ----------- +Maintenance Submodules +----------------------

scripts.maintenance.cache script -------------------------------- diff --git a/docs/tests_ref/pwb.rst b/docs/tests_ref/pwb.rst index 4369026..ccdbd1a 100644 --- a/docs/tests_ref/pwb.rst +++ b/docs/tests_ref/pwb.rst @@ -6,8 +6,8 @@ :undoc-members: :show-inheritance:

-Submodules ----------- +pwb submodules +--------------

.. toctree::

diff --git a/pywikibot/site/_extensions.py b/pywikibot/site/_extensions.py index 1290db8..66f4d59 100644 --- a/pywikibot/site/_extensions.py +++ b/pywikibot/site/_extensions.py @@ -398,7 +398,7 @@ :param toconly: Whether to only include information for the TOC. :type toconly: bool :param offset: The timestamp to start at (when sortby is 'updated'). - :type offset: Timestamp or equivalent str + :type offset: time.Timestamp or equivalent str :param offset_id: The topic UUID to start at (when sortby is 'newest'). :type offset_id: str (in the form of a UUID) :param reverse: Whether to reverse the topic ordering. diff --git a/pywikibot/site/_generators.py b/pywikibot/site/_generators.py index 49ca8ca..d363abc 100644 --- a/pywikibot/site/_generators.py +++ b/pywikibot/site/_generators.py @@ -493,7 +493,7 @@ (default False) :param starttime: if provided, only generate pages added after this time; not valid unless sortby="timestamp" - :type starttime: pywikibot.Timestamp + :type starttime: time.Timestamp :param endtime: if provided, only generate pages added before this time; not valid unless sortby="timestamp" :param startprefix: if provided, only generate pages >= this title @@ -1115,9 +1115,9 @@ ``iprange`` parameter cannot be used together with ``users``.

:param starttime: start iterating at this Timestamp - :type starttime: pywikibot.Timestamp + :type starttime: time.Timestamp :param endtime: stop iterating at this Timestamp - :type endtime: pywikibot.Timestamp + :type endtime: time.Timestamp :param reverse: if True, iterate oldest blocks first (default: newest) :param blockids: only iterate blocks with these id numbers. Numbers must be separated by '|' if given by a str. @@ -1254,9 +1254,9 @@ the API and will be filtered later during iteration.

:param start: only iterate entries from and after this Timestamp - :type start: Timestamp or ISO date string + :type start: time.Timestamp or ISO date string :param end: only iterate entries up to and through this Timestamp - :type end: Timestamp or ISO date string + :type end: time.Timestamp or ISO date string :param reverse: if True, iterate oldest entries first (default: newest) :param tag: only iterate entries tagged with this tag :param total: maximum number of events to iterate diff --git a/pywikibot/tools/_deprecate.py b/pywikibot/tools/_deprecate.py index 22da253..885dbfc 100644 --- a/pywikibot/tools/_deprecate.py +++ b/pywikibot/tools/_deprecate.py @@ -5,9 +5,9 @@ a different invocation to @deprecated().

The former is invoked with the decorated function as args[0]. -The latter is invoked with the decorator arguments as *args & **kwargs, -and it must return a callable which will be invoked with the decorated -function as args[0]. +The latter is invoked with the decorator arguments as ``*args`` & +``**kwargs``, and it must return a callable which will be invoked with +the decorated function as args[0].

The follow deprecators may support both syntax, e.g. @deprecated and @deprecated() both work. In order to achieve that, the code inspects @@ -500,7 +500,7 @@ parameters.

.. versionchanged:: 7.0 - `since`parameter must be a release number, not a timestamp. + ``since`` parameter must be a release number, not a timestamp.

:param target: The targeted function which is to be executed. :type target: callable @@ -579,7 +579,7 @@ Add the name to the local deprecated names dict.

.. versionchanged:: 7.0 - `since`parameter must be a release number, not a timestamp. + ``since`` parameter must be a release number, not a timestamp.

:param name: The name of the deprecated class or variable. It may not be already deprecated. diff --git a/pywikibot/tools/collections.py b/pywikibot/tools/collections.py index b536e7a..a4cd8a3 100644 --- a/pywikibot/tools/collections.py +++ b/pywikibot/tools/collections.py @@ -267,7 +267,7 @@ The `value` parameter is ignored yet; usually it should be ``None``. If the wrapped generator property exits without yielding another value this method raises `StopIteration`. The send method works - like the `next`function with a GeneratorWrapper instance as + like the `next` function with a GeneratorWrapper instance as parameter.

Refer :python:`generator.send() diff --git a/scripts/category.py b/scripts/category.py index 3b25670..334f093 100755 --- a/scripts/category.py +++ b/scripts/category.py @@ -1049,6 +1049,7 @@

.. note:: current_cat is only used for internal recursion. You should always use ``current_cat = original_cat``. + :param member: a page to process. :param original_cat: original category to replace. :param current_cat: a category which is questioned. diff --git a/scripts/replace.py b/scripts/replace.py index cdc730c..3825cae 100755 --- a/scripts/replace.py +++ b/scripts/replace.py @@ -520,12 +520,14 @@ :keyword always: the user won't be prompted before changes are made :type keyword: bool :keyword site: Site the bot is working on. + .. warning:: - Be careful with `recursive` parameter, this might lead to an infinite loop. - `site` parameter should be passed to constructor. Otherwise the bot takes the current site and warns the operator about the missing site + """

def __init__(self, generator, diff --git a/tests/archivebot_tests.py b/tests/archivebot_tests.py index 0a7bbf5..8593877 100755 --- a/tests/archivebot_tests.py +++ b/tests/archivebot_tests.py @@ -295,12 +295,12 @@ def testLoadConfigInTemplateNamespace(self): """Test loading of config with TEMPLATE_PAGE in Template ns.

- Talk:For-pywikibot-archivebot-01 must have: + Talk:For-pywikibot-archivebot-01 must have::

- {{Pywikibot_archivebot - |archive = Talk:Main_Page/archive - |algo = old(30d) - }} + {{Pywikibot_archivebot + |archive = Talk:Main_Page/archive + |algo = old(30d) + }} """ site = self.get_site() page = pywikibot.Page(site, 'Talk:For-pywikibot-archivebot-01') @@ -322,12 +322,12 @@ def testLoadConfigInOtherNamespace(self): """Test loading of config with TEMPLATE_PAGE not in Template ns.

- Talk:For-pywikibot-archivebot must have: + Talk:For-pywikibot-archivebot must have::

- {{User:MiszaBot/config - |archive = Talk:Main_Page/archive - |algo = old(30d) - }} + {{User:MiszaBot/config + |archive = Talk:Main_Page/archive + |algo = old(30d) + }} """ site = self.get_site() page = pywikibot.Page(site, 'Talk:For-pywikibot-archivebot')