Project:Pywikibot/Documentation RFC
February 2016
Based on the Lyon Hackathon discussion and some later IRC discussions, I have started to clean up the pywikibot manual. I have classified all current pages into five categories:
- documentation on getting started and running an existing bot? Keep, but clean up
- documentation on scripts: Move to Manual:Pywikibot/Scripts/ and update for core
- compat-only page? Move to Manual:Pywikibot/Compat/ and document on Manual:Pywikibot/Compat (done)
- discussion page? Move to Project: namespace, (done)
- documentation on writing a bot? Move to doc.wm.o
- documentation on contributing to pywikbot? Move to doc.wm.o
Conclusion from Lyon Hackathon discussion
See https://etherpad.wikimedia.org/p/Pywikibot_doc_sprint / https://phabricator.wikimedia.org/T100109#1306324
pywikibot documentation
This is an initial braindump on issues with the current pywikibot documentation and possible solutions, by Valhallasw (talk) 19:49, 20 May 2014 (UTC).
Current issues
- The documentation is spread out. There is the documentation here on mw.org, but also documentation on basically every Wikipedia (e.g. nl:Help:Gebruik_van_bots), every wikibook and even on wikiversity. Then there's also botwiki: and various guides on wikia. There should be only one authoritative and comprehensive place for users to go for help.
- The documentation is outdated. The wikia links above are the worst (Python 2.3 and CVS), but even more recent documentation is only valid for compat, and often documentation does not clarify for which version it was written. The documentation is rarely updated by developers.
- The documentation lacks structure. This is, of course, a direct result of the wiki structure. People add a page to write down what they did, instead of trying to merge it into the central documentation, or they add documentation in a section it doesn't really belong.
- There is no API documentation
The good things
There are also some things awesome with the current documentation:
- It's really easy to contribute: anyone with an mw.org account can edit/improve a page;
- Documentation can be translated relatively easily (which is important)
- Documentation is in a sensible location -- the same place as MediaWiki documentation.
What can we do?
To tackle the 'bad' points mentioned above, I think there are a few things we should get:
- Curation: developers need to take an active role in curating content added to the documentation by others (spread out; outdated; structure)
- Developers need to take an active role in keeping documentation up to date (spread out; outdated)
- Some sort of automated documentation generation (outdated; API docs)
However, we should do that without losing the good points mentioned above.
Options
A few possible options:
| Curation | Active updating | Auto-docs | Easy contribution | Translations | Location | Availability | |
|---|---|---|---|---|---|---|---|
| Status quo
(docs on mw.org) |
 Negative
No active review possible (Flaggedrevs has been disabled) |
Negative
Outside the normal developer workflow and therefore hard to enforce. |
 Neutral- Positive
Possible with bots |
Positive
SUL login; familiar syntax and interface |
Positive
Built-in |
Positive
mw.org |
Positive
status quo |
| Sphinx
(docs on docs.mw.org or readthedocs) |
Positive
Changes pass through Gerrit |
Positive
Changes pass through Gerrit, so patches can be held for merge until documentation is added. |
Positive
sphinx-autodoc can create documentation from code docstrings |
Negative
Needs git; uses ReStructuredText instead of wikitext; previewing is difficult (needs local installation) |
Negative
Sphinx does support it via .po files, but these also would need updating. Maybe possible via translatewiki? |
Neutral
docs.mw.org is hard to find; readthedocs is used a lot for python apps, so good from the framework perspective |
Neutral
initial attempt in Gerrit |
| Hybrid (A)
Documentation in git, exported to (locked) pages on wiki |
Positive
Changes pass through Gerrit |
Positive
Changes pass through Gerrit, so patches can be held for merge until documentation is added. |
Neutral- Negative
Full doc-gen to mediawiki is difficult: sphinx has no MW output and sphinx.autodoc is hard to use outside of sphinx |
Negative
Needs git; previewing is difficult (probably would need to edit on-wiki, then copy-paste to editor?); wikitext is familiar. |
Positive
On mw.org |
Positive
mw.org |
Neutral- Negative
needs a dump of Help:Pywikibot/* pages to text files & a bot/jenkins job to update pages on-wiki |
| Hybrid (B)
Documentation in git, but with a wiki-to-git bridge. |
Positive
Changes pass through Gerrit |
Positive
Changes pass through Gerrit, so patches can be held for merge until documentation is added. |
Neutral- Positive
Should be possible through jenkins, maybe with some sphinx-autodoc help? |
Positive
No git necessary; previewing is easy (built-in!), wikitext is familiar |
Positive
On mw.org |
Positive
mw.org |
Negative
needs a dump of Help:Pywikibot/* pages to text files, a bot/jenkins job to update pages on-wiki as well as some way to move wiki edits to git |
Suggestions from pywikibot gold-standard evaluation
As a part of the gold standard evaluation for pywikibot, I identified several documentation-related issues: API:Client code/Evaluations/Pywikibot#Suggested TODOs. --Fhocutt (talk) 19:07, 25 July 2014 (UTC)
Changes that would improve the documentation include:
- Add code samples to the documentation to provide easy-to-use examples for common tasks (including queries/lists/searches and edits)
- Add easy-to-find, complete, and intuitive installation instructions to the documentation. This should include installation via pip (https://bugzilla.wikimedia.org/show_bug.cgi?id=65176) and into virtual environments (https://bugzilla.wikimedia.org/show_bug.cgi?id=61783).
- Add documentation for people who aren't running bots with existing scripts (particularly researchers who extract data via the API and beginning/intermediate bot writers).
- Method docstrings should include a link to the corresponding mw:API subpage.