Doctest

[BalzaniEdoardo]

• Added doctest to tox.ini run by pytest for checking module docstrings
• Fixed example to pass the tests
• Added mpl as dev dependency (needed by doctest to run examples)

Note: I needed to capture outputs of fits and plots because they have a repr that prints the memory address of the object while for doctest the output of the console must be matched exactly.

[BalzaniEdoardo]

Additionally, I am ignoring the fetch and _documentation_utils modules because one would require pooch as dev dependency and the other would require seaborn

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.24%. Comparing base (6dcd891) to head (9b1bb78).

Additional details and impacted files

@@             Coverage Diff              @@
##           development     #232   +/-   ##
============================================
  Coverage        97.24%   97.24%           
============================================
  Files               20       20           
  Lines             1815     1815           
============================================
  Hits              1765     1765           
  Misses              50       50           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[billbrod]

As I'm going through this, I think I'm not quite understanding what doctests do. Can you add a brief description? That should probably live in CONTRIBUTING.md. You could write up when they're necessary (note that pyopensci is going to ask you to have them for every public-facing function, so I'd say that, even if it's currently aspirational), how to write them, and what they'll check.

• I'm confused as to why in some places the doctests includes the expected output and sometimes in doesn't. (Compare e.g., TransformerBasis.set_params and TransformerBasis).
• Why the changing of some docstrings from strings to raw string literals? (with the addition of r)? My understanding is that the main difference has to do with the treatment of \, but most of those docstrings seem to not have any?
• Up to you of course, but I think it's fine to include pooch and seaborn as dev dependencies, so that we can run the docstring tests on the whole tree. The dev bundle is really just for our convenience -- no one has to install them.

[BalzaniEdoardo]

As I'm going through this, I think I'm not quite understanding what doctests do. Can you add a brief description? That should probably live in CONTRIBUTING.md. You could write up when they're necessary (note that pyopensci is going to ask you to have them for every public-facing function, so I'd say that, even if it's currently aspirational), how to write them, and what they'll check.

Added a section on doctest in the CONTRIBUTING.md

* I'm confused as to why in some places the doctests includes the expected output and sometimes in doesn't. (Compare e.g., `TransformerBasis.set_params` and `TransformerBasis`).

when you capture the output storing it into the variable, no out is displayed (example out = TransformerBasis(basis) doesn't expect any out), .

* Why the changing of some docstrings from strings to raw string literals? (with the addition of `r`)? My understanding is that the main difference has to do with the treatment of `\`, but most  of those docstrings seem to not have any?

I needed in some multiline examples but I might have used it even if not necessary. I'll check on a case by case way.

* Up to you of course, but I think it's fine to include pooch and seaborn as dev dependencies, so that we can run the docstring tests on the whole tree. The dev bundle is really just for our convenience -- no one has to install them.

I move both to dev.

[billbrod]

Two notes:

• CONTRIBUTING should tell people what to do if they'd like to contribute. The tone of your doctest section is "suggesting", but it should be more declarative. Something like: "when you add a public function or method, you will need to include an examples section. This should be formatted as a doctest, which allows pytest to run the code as part of our testing suite. If you do not capture the output (e.g., >>> x + y vs. >>> z = x + y), the next line will need to show the expected output (e.g., 3) and the doctests will ensure that output matches. See below for an example..." Similarly, should provide some guidance on when to include doctests in text files.
• Currently, not running doctests on the text files. Is it possible to come up with a general enough command to include in the tox?

[BalzaniEdoardo]

I moved into an issue the idea of running doctests for all text files. I think it is true, but not in this PR because all examples needs to be reformatted!