Page MenuHomePhabricator

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


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

They are included in the generated documentation, such as , 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 ( 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/
Do not create doctest for

  • Exception or Warning subclasses (i.e. everything in pywikibot/,
  • Family classes (i.e. pywikibot/families/*.py),
  • private classes (i.e. name beginning with '_')
  • classes that are unused or only used by scripts/ (e.g. pywikibot/ IRCBot is only used by scripts/
  • '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.

I am new to OpenSource and I would like to work on this task can someone mentor me for this task?

Xqt added a subscriber: Xqt.Sun, Sep 27, 8:50 AM

I am new to OpenSource and I would like to work on this task can someone mentor me for this task?

Sure. Ask if you have any questions.

Hi. If the issue is not taken, I'd like to contribute in it? Please reply!