[[https://en.wikipedia.org/wiki/Doctest | doctest]] are pieces of text in [[https://en.wikipedia.org/wiki/Docstring|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 [[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.
Mentor: @jayvdb