Page MenuHomePhabricator

Pywikibot: Insufficient documentation
Open, Needs TriagePublic


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

Docs targeting bot users

  • 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 watchlist. However the syntax example in scripts/ has this python 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., '') 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

Change 790791 merged by jenkins-bot:

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

The lead documentation is on because it is generated from the code automatically.
See also:
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

Docs targeting bot developers

  • Need simple documentation for bot writers

There is a script sample shipped with the framework, see

  • Need more code samples around available classes and methods on

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


komla updated the task description. (Show Details)

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