Use doctest to execute examples in the docstring

[sdesrozis]

📚 Documentation

Example snippets are inserted into the docstring to show usage. However, these pieces of code might be deprecated, or might not work. The module doctest aims to execute the tests written in docstring and it works fine with sphinx. It could help to detect earlier doc issues and provide a better doc.

Useful links

• https://docs.python.org/3/library/doctest.html
• https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html

Note that some tests was written according to doctest

ignite/ignite/handlers/timing.py

Line 30 in b3d9849

>>> from ignite.handlers import Timer

The main point is the refactoring of every test to pass the validation. It means have consistent pieces of code (define training fn, engines, etc.) to provide reproducible examples.

[vfdev-5]

Interesting idea. I think Jeff or Taras proposed already something like that previously. Probably we wont be able to execute all doc snippets like ddp etc

[sdesrozis]

Interesting idea. I think Jeff or Taras proposed already something like that previously. Probably we wont be able to execute all doc snippets like ddp etc

Of course, but it could help to keep most examples correct.

[DevPranjal]

Hello @sdesrozis, @vfdev-5, I'd like to work on the Ignite docs, can you provide some more details about this issue? Do we have to check each doctest for deprecation? Or do we have to refactor the doctests to a follow a particular template?

[sdesrozis]

A good first point would be to check whether doctest would help. Maybe we could choose a module and see how it helps. Meanwhile we must assess the required effort for the rest of the doc.

I propose to focus on a few metrics. Select ones having a piece of example code inside the docstring and check how doctest + sphinx extension works. A test must be added in the test base of the selected metric in order to validate the docstring example. What do you think ?

Anyway, I think this issue is a huge effort. We have to do it carefully according to others actions on the doc. Concretely the first point you would do should help to discuss and plan with the team.

[DevPranjal]

Since this is a fast developing library, I think it would be great to have doctests to stay updated on the docs. I will start looking into how doctests work with sphinx.

[vfdev-5]

@sdesrozis can we close this issue as solved or still there is something to be done ?

[sdesrozis]

It's done !