Page MenuHomePhabricator

[clonable] Add doctests to Pywikibot library documentation
Open, MediumPublic

Description

doctest are pieces of text in docstrings that look like interactive Python sessions.

They are included in the generated documentation, such as https://doc.wikimedia.org/pywikibot/api_ref/pywikibot.data.html#pywikibot.data.api.Request , allowing quicker understanding of how to use a class or function.

Pywikibot only has a few doctest.
However Pywikibot has many unittests in tests, which can be used as the basis of new doctest.

doctest in patches uploaded into Gerrit are tested by Jenkins using the tox.ini rules nose and nose34.
However doctest will fail in Jenkins if they use network resources (https://gerrit.wikimedia.org/r/#/c/256212 will fix this). If a doctest will use network resources, the module should be added to the tox.ini pattern nose_skip.

Easy GCI task: amend the docstring for a class or generator function in pywikibot/ to include a doctest with at least seven lines of python, and at least five lines of output.
Many generator functions can be found in pywikibot/pagegenerators.py
Do not create doctest for

  • Exception or Warning subclasses (i.e. everything in pywikibot/exceptions.py),
  • Family classes (i.e. pywikibot/families/*.py),
  • private classes (i.e. name beginning with '_')
  • classes that are unused or only used by scripts/script_wui.py (e.g. pywikibot/botirc.py:class IRCBot is only used by scripts/script_wui.py)
  • 'base' classes that are only used as super classes and never used directly (e.g. 'Family`, UI, BasePage, WikibasePage and BaseSite)

doctest for 'mixin' classes (they are usually named ..Mixin such as UnicodeMixin and ComparableMixin) must define and use an example class.

Mentor: @jayvdb

Event Timeline

jayvdb created this task.Dec 1 2015, 9:28 PM
jayvdb raised the priority of this task from to Medium.
jayvdb updated the task description. (Show Details)
jayvdb added a subscriber: jayvdb.
Restricted Application added a project: Documentation. · View Herald TranscriptDec 1 2015, 9:28 PM
Restricted Application added subscribers: pywikibot-bugs-list, Aklapper. · View Herald Transcript

Are you still interested in mentoring this task? I see we have some similar ones in GCI (T118423, T121365, T121366) but not this one yet.