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.