scikit-matter icon indicating copy to clipboard operation
scikit-matter copied to clipboard

Switch to sphinx doctest to avoid implicit import problem

Open agoscinski opened this issue 1 year ago • 1 comments

Hello when I replaced the code snippets in PR https://github.com/scikit-learn-contrib/scikit-matter/pull/201 I used sphinx doctest to have them in the docs/src, but in PR https://github.com/scikit-learn-contrib/scikit-matter/pull/202 we move it to an __init__ file, so we don't need sphinx doctest anymore. But I noticed that with sphinx doctest the implicit problem does not exist:

import numpy as np

#. ..
class SomeClass:
    """
    >>> a = np.array([5])
    """
    pass

The doctest in pytest does not fail because it gets the import at the beginning of the file, but when one sees the example in the doc or help page, one does not know this. So one has to remember to add imports into the doctest when using pytest. With sphinx doctest this test would fail because of the missing import. Therefore this issue is to discuss a switch to sphinx doctest. There might be some downsides using sphinx doctest that I have not realized yet.

Also @PicoCentauri suggests move the sphinx doctest then to the test environment in tox which makes sense. After the PR https://github.com/scikit-learn-contrib/scikit-matter/pull/202 we do not have any doctest in the docs, so I think we can do it.

agoscinski avatar Aug 14 '23 08:08 agoscinski