Page MenuHomePhabricator

Pywikibot: Insufficient documentation
Open, Needs TriagePublic

Description

Some observations while developing workshop materials around Pywikibot as part of the Small-Wiki-Toolkits initiative:

Docs targeting bot users
https://www.mediawiki.org/wiki/Manual:Pywikibot/Scripts

  • Documents kept only for historical purposes are still linked from the "scripts" page.
  • Some pages do not demonstrate the use of essential parameters / arguments well
    • The watchlist script documentation says "there appears to be no arguments which can be used with it. Just type python pwb.py watchlist. However the syntax example in scripts/watchlist.py has this python pwb.py watchlist [-all | -count | -count:all | -new]. Though command line flags are technically different from command line arguments, can this made more explicit?
  • Some pages still use options or parameters that are deprecated
  • Some scripts are even missing pages and still appear in red links on the landing page
  • Scripts categorization needs a review and overhaul. For example, some scripts that do category work (e.g., 'category.py') are placed under the "Main bot scripts" section when they should be under the "Categories" section.

Docs targeting bot developers

See also

Event Timeline

IMHO this should be declined and split into separate tasks with specific pages listed, because catch-alls are way way harder to ever get resolved. See also T288833. Edit: Looks like this task had more background and momentum than I assumed when writing my comment. Sorry!

Change 790791 had a related patch set uploaded (by Xqt; author: Xqt):

[pywikibot/core@master] [doc] Fix library usage description

https://gerrit.wikimedia.org/r/790791

Change 790791 merged by jenkins-bot:

[pywikibot/core@master] [doc] Fix library usage description

https://gerrit.wikimedia.org/r/790791

The lead documentation is on https://doc.wikimedia.org/pywikibot because it is generated from the code automatically.
See also: https://www.mediawiki.org/wiki/Project:Pywikibot/Documentation_RFC#Options
Maybe the MediaWiki pages should link to the corresponding doc pages or they should be synchronized somehow.

Docs targeting bot users

For the script package and scripts description and usage refer https://doc.wikimedia.org/pywikibot/stable/scripts/index.html.

Docs targeting bot developers

  • Need simple documentation for bot writers

There is a basic.py script sample shipped with the framework, see https://doc.wikimedia.org/pywikibot/master/library_usage.html#basic-script

  • Need more code samples around available classes and methods on MediaWiki.org.

I think this should be documentend within the code itself; doctests ensures that the samples are right

Samples:

komla updated the task description. (Show Details)

As an idea for sync code documentation with mw manual see T194714