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 [[https://github.com/wikimedia/pywikibot-core/tree/master/tests | tests]], which can be used as the basis of new doctest.
doctest in patches uploaded into Gerrit are tested by Jenkins using the [[https://github.com/wikimedia/pywikibot-core/blob/master/tox.ini | 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.