DOC: add a doctest step to CI to allow writing testable code blocs, fix existing docstring code examples errors (#592)

* DOC: add a doctest step to CI to allow writing testable code blocs, fix existing docstring code examples errors

Author: Valentin-Laurent

.github/PULL_REQUEST_TEMPLATE.md

@@ -24,8 +24,9 @@ Please describe the tests that you ran to verify your changes. Provide instructi
 
 - [ ] I have read the [contributing guidelines](https://github.com/scikit-learn-contrib/MAPIE/blob/master/CONTRIBUTING.rst)
 - [ ] I have updated the [HISTORY.rst](https://github.com/scikit-learn-contrib/MAPIE/blob/master/HISTORY.rst) and [AUTHORS.rst](https://github.com/scikit-learn-contrib/MAPIE/blob/master/AUTHORS.rst) files
-- [ ] Linting passes successfully : `make lint`
-- [ ] Typing passes successfully : `make type-check`
-- [ ] Unit tests pass successfully : `make tests`
-- [ ] Coverage is 100% : `make coverage`
-- [ ] Documentation builds successfully and without warnings : `make doc`
+- [ ] Linting passes successfully: `make lint`
+- [ ] Typing passes successfully: `make type-check`
+- [ ] Unit tests pass successfully: `make tests`
+- [ ] Coverage is 100%: `make coverage`
+- [ ] When updating documentation: doc builds successfully and without warnings: `make doc`
+- [ ] When updating documentation: code examples in doc run successfully: `make doctest`

.readthedocs.yml

@@ -4,6 +4,9 @@ build:
   os: ubuntu-22.04
   tools:
     python: "mambaforge-22.9"
+  jobs:
+    post_build:
+      - cd doc && make doctest
 
 python:
   install:

HISTORY.rst

@@ -15,6 +15,7 @@ History
 * Limit max sklearn version allowed at MAPIE installation
 * Refactor MapieRegressor, EnsembleRegressor, and MapieQuantileRegressor, to prepare for the release of v1.0.0
 * Documentation build: fix warnings, fix image generation, update sklearn version requirement
+* Documentation test: add a doc testing step (in MAKEFILE and CI)
 * Increase max line length from 79 to 88 characters
 * Bump wheel version
 

Makefile

@@ -22,6 +22,9 @@ coverage:
 doc:
 	$(MAKE) html -C doc
 
+doctest:
+	$(MAKE) doctest -C doc
+
 clean-doc:
 	$(MAKE) clean -C doc
 

mapie/metrics.py

@@ -560,7 +560,7 @@ def regression_ssc_score(
 
     Examples
     --------
-    >>> from mapie.metrics import regression_ssc
+    >>> from mapie.metrics import regression_ssc_score
     >>> import numpy as np
     >>> y_true = np.array([5, 7.5, 9.5])
     >>> y_intervals = np.array([
@@ -1283,6 +1283,7 @@ def kolmogorov_smirnov_p_value(y_true: NDArray, y_score: NDArray) -> float:
     Examples
     --------
     >>> import pandas as pd
+    >>> import numpy as np
     >>> from mapie.metrics import kolmogorov_smirnov_p_value
     >>> y_true = np.array([1, 0, 1, 0, 1, 0])
     >>> y_score = np.array([0.8, 0.3, 0.5, 0.5, 0.7, 0.1])
@@ -1450,6 +1451,7 @@ def kuiper_p_value(y_true: NDArray, y_score: NDArray) -> float:
     Examples
     --------
     >>> import pandas as pd
+    >>> import numpy as np
     >>> from mapie.metrics import kuiper_p_value
     >>> y_true = np.array([1, 0, 1, 0, 1, 0])
     >>> y_score = np.array([0.8, 0.3, 0.5, 0.5, 0.7, 0.1])

mapie/mondrian.py

@@ -72,6 +72,7 @@ class MondrianCP(BaseEstimator):
     >>> import numpy as np
     >>> from sklearn.linear_model import LogisticRegression
     >>> from mapie.classification import MapieClassifier
+    >>> from mapie.mondrian import MondrianCP
     >>> X_toy = np.arange(9).reshape(-1, 1)
     >>> y_toy = np.stack([0, 0, 1, 0, 1, 2, 1, 2, 2])
     >>> partition_toy = [0, 0, 0, 0, 1, 1, 1, 1, 1]