docs: Refine the documentation before the release 0.6.1 (#1204)

Various minor stuff --------- Co-authored-by: MarieS-WiMLDS <[email protected]> Co-authored-by: Marie <[email protected]>
probabl-ai · Jan 22, 2025 · c3e28ee · c3e28ee
1 parent 687316d
commit c3e28ee
Show file tree

Hide file tree

Showing 4 changed files with 11 additions and 6 deletions.
diff --git a/examples/getting_started/plot_skore_getting_started.py b/examples/getting_started/plot_skore_getting_started.py
@@ -253,7 +253,7 @@
 # .. seealso::
 #
 #   For more information about the motivation and usage of
-#   :class:`skore.CrossValidationReport`, see :ref:`example_cross_validate`.
+#   :class:`skore.CrossValidationReport`, see :ref:`_example_use_case_employee_salaries`.
 
 # %%
 # Train-test split with skore

diff --git a/examples/model_evaluation/plot_estimator_report.py b/examples/model_evaluation/plot_estimator_report.py
@@ -10,8 +10,10 @@
 """
 
 # %%
-#
-# TODO: we need to describe the aim of this classification problem.
+# First, we load a dataset from skrub. Our goal is to predict if a company paid a physician. The ultimate goal is to
+# detect potential conflict of interest when it comes to the actual problem that we want to solve.
+
+# %%
 from skrub.datasets import fetch_open_payments
 
 dataset = fetch_open_payments()
@@ -44,8 +46,8 @@
 X_train, X_test, y_train, y_test = train_test_split(df, y, random_state=42)
 
 # %%
-# TODO: we have a perfect case to show useful feature of the `train_test_split`
-# function from `skore`.
+# By the way, notice how skore's :func:`~train_test_split` automatically warns us for a
+# class imbalance.
 #
 # Now, we need to define a predictive model. Hopefully, `skrub` provides a convenient
 # function (:func:`skrub.tabular_learner`) when it comes to getting strong baseline
@@ -224,7 +226,6 @@ def operational_decision_cost(y_true, y_pred, amount):
     mask_true_negative = (y_true == neg_label) & (y_pred == neg_label)
     mask_false_positive = (y_true == neg_label) & (y_pred == pos_label)
     mask_false_negative = (y_true == pos_label) & (y_pred == neg_label)
-    # FIXME: we need to make sense of the cost sensitive part with the right naming
     fraudulent_refuse = mask_true_positive.sum() * 50
     fraudulent_accept = -amount[mask_false_negative].sum()
     legitimate_refuse = mask_false_positive.sum() * -5

diff --git a/examples/technical_details/plot_cache_mechanism.py b/examples/technical_details/plot_cache_mechanism.py
@@ -1,4 +1,6 @@
 """
+.. _example_cache_mechanism:
+
 ===============
 Cache mechanism
 ===============

diff --git a/examples/use_cases/plot_employee_salaries.py b/examples/use_cases/plot_employee_salaries.py
@@ -1,4 +1,6 @@
 """
+.. _example_use_case_employee_salaries:
+
 ===============================
 Simplified experiment reporting
 ===============================