docs: Modify the doc following the v0.5 release, part 1 (#1004)

Fix #1007
probabl-ai · Dec 24, 2024 · fda5feb · fda5feb
1 parent 43578dd
commit fda5feb
Show file tree

Hide file tree

Showing 16 changed files with 167 additions and 126 deletions.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -4,8 +4,8 @@
 Contributing
 ============
 
-First off, thanks for taking the time to contribute, everyone is welcome to
-contribute.
+Thank you for your interest in contributing to Skore! We welcome contributions from
+everyone and appreciate you taking the time to get involved.
 
 This project is hosted on https://github.com/probabl-ai/skore.
 

diff --git a/README.md b/README.md
@@ -84,8 +84,8 @@ You can find information on the latest version [here](https://anaconda.org/conda
     # Store the results in the project
     my_project.put("cv_reporter", reporter)
 
-    # Display the result in your notebook
-    reporter.plot
+    # Display a plot result in your notebook
+    reporter.plots.scores
     ```
 
 3. Finally, from your shell (in the same directory), start the UI:

diff --git a/examples/README.txt b/examples/README.txt
@@ -1,7 +1,7 @@
 .. _auto_examples:
 
-Examples
-========
+User guide
+==========
 
 Below is a gallery of narrated notebook examples on how and why to use skore.
-They also serve as our user guide.
+They serve as our user guide.
diff --git a/examples/getting_started/README.txt b/examples/getting_started/README.txt
@@ -1,5 +1,4 @@
 Getting started
 ---------------
 
-We recommend first having a look at this example that serves as an overall and gentle
-introduction to skore.
+We recommend first having a look at the :ref:`example_quick_start` page. Then, the :ref:`example_skore_product_tour` provides an overall and gentle introduction to skore.
diff --git a/examples/getting_started/plot_quick_start.py b/examples/getting_started/plot_quick_start.py
@@ -0,0 +1,62 @@
+"""
+.. _example_quick_start:
+
+===========
+Quick start
+===========
+"""
+
+# %%
+# From your Python code, create and load a skore :class:`~skore.Project`:
+
+# %%
+import skore
+
+my_project = skore.create("quick_start", overwrite=True)
+
+# %%
+# This will create a skore project directory named ``quick_start.skore`` in your
+# current working directory.
+
+# %%
+# Evaluate your model using skore's :class:`~skore.CrossValidationReporter`:
+
+# %%
+from sklearn.datasets import load_iris
+from sklearn.svm import SVC
+
+X, y = load_iris(return_X_y=True)
+clf = SVC(kernel="linear", C=1, random_state=0)
+
+reporter = skore.CrossValidationReporter(clf, X, y, cv=5)
+
+# %%
+# Store the results in the skore project:
+
+# %%
+my_project.put("cv_reporter", reporter)
+
+# %%
+# Display results in your notebook:
+
+# %%
+reporter.plots.scores
+
+# %%
+reporter.plots.timing_normalized
+
+# %%
+# Finally, from your shell (in the same directory), start the UI:
+#
+# .. code-block:: bash
+#
+#   $ skore launch "quick_start"
+#
+# This will open skore-ui in a browser window.
+#
+# .. image:: https://media.githubusercontent.com/media/probabl-ai/skore/main/sphinx/_static/images/2024_12_12_skore_demo_comp.gif
+#   :alt: Getting started with ``skore`` demo
+#
+# .. admonition:: What's next?
+#
+#    For a more in-depth guide, see our :ref:`example_skore_product_tour` page!
diff --git a/...s/getting_started/plot_getting_started.py → ...etting_started/plot_skore_product_tour.py b/...s/getting_started/plot_getting_started.py → ...etting_started/plot_skore_product_tour.py
@@ -1,11 +1,16 @@
 """
-.. _example_getting_started:
+.. _example_skore_product_tour:
 
-==========================
-Getting started with skore
-==========================
+==================
+Skore product tour
+==================
 """
 
+# %%
+# .. admonition:: Where to start?
+#
+#    See our :ref:`example_quick_start` page!
+
 # %%
 # This getting started guide illustrates how to use skore and why:
 #
@@ -149,7 +154,7 @@
 #
 #   For more information about the functionalities and the different types
 #   of items that we can store in a skore :class:`~skore.Project`,
-#   see :ref:`example_overview_skore_project`.
+#   see :ref:`example_working_with_projects`.
 
 # %%
 # Skore UI: visualizing items
@@ -211,7 +216,7 @@
 # .. seealso::
 #
 #   For more information about the tracking of items using their history,
-#   see :ref:`example_historization_items`.
+#   see :ref:`example_tracking_items`.
 
 # %%
 # Machine learning diagnostics: enhancing scikit-learn functions

diff --git a/examples/track/plot_tracking_items.py → ...es/getting_started/plot_tracking_items.py b/examples/track/plot_tracking_items.py → ...es/getting_started/plot_tracking_items.py
@@ -1,9 +1,9 @@
 """
-.. _example_historization_items:
+.. _example_tracking_items:
 
-==================================
-Tracking items using their history
-==================================
+==============
+Tracking items
+==============
 
 This example illustrates how skore can be used to track some items using their history,
 for example tracking some ML metrics over time.
@@ -79,11 +79,11 @@
 # We can print the first history (first iteration) of this item:
 
 # %%
-item_history = item_histories[0]
-print(item_history)
-print(item_history.primitive)
-print(item_history.created_at)
-print(item_history.updated_at)
+passed_item = item_histories[0]
+print(passed_item)
+print(passed_item.primitive)
+print(passed_item.created_at)
+print(passed_item.updated_at)
 
 # %%
 # Let us construct a dataframe with the values and last updated times:

diff --git a/...ples/track/plot_overview_skore_project.py → ...ing_started/plot_working_with_projects.py b/...ples/track/plot_overview_skore_project.py → ...ing_started/plot_working_with_projects.py
@@ -1,9 +1,9 @@
 """
-.. _example_overview_skore_project:
+.. _example_working_with_projects:
 
-=============================
-Overview of the skore project
-=============================
+=====================
+Working with projects
+=====================
 
 This example provides an overview of the functionalities and the different types
 of items that we can store in a skore :class:`~skore.Project`.
@@ -68,7 +68,7 @@
 #
 #   Skore does not exactly *overwrite*, but stores the history of items.
 #   For more information about the tracking of items using their history,
-#   see :ref:`example_historization_items`.
+#   see :ref:`example_tracking_items`.
 
 # %%
 # By using the :func:`~skore.Project.delete_item` method, we can also delete an object

diff --git a/examples/diagnose/README.txt → examples/model_evaluation/README.txt b/examples/diagnose/README.txt → examples/model_evaluation/README.txt
@@ -1,5 +1,5 @@
-Diagnose
---------
+Model evaluation
+----------------
 
 These examples illustrate how skore can help data scientists to improve their
 machine learning modelling thanks to diagnostics.
diff --git a/examples/diagnose/plot_cross_validate.py → ...s/model_evaluation/plot_cross_validate.py b/examples/diagnose/plot_cross_validate.py → ...s/model_evaluation/plot_cross_validate.py
@@ -1,9 +1,9 @@
 """
 .. _example_cross_validate:
 
-==========================
-Enhancing cross-validation
-==========================
+================
+Cross-validation
+================
 
 This example illustrates the motivation and the use of skore's
 :class:`skore.CrossValidationReporter` to get assistance when developing ML/DS projects.

diff --git a/examples/diagnose/plot_train_test_split.py → ...model_evaluation/plot_train_test_split.py b/examples/diagnose/plot_train_test_split.py → ...model_evaluation/plot_train_test_split.py
@@ -1,9 +1,9 @@
 """
 .. _example_train_test_split:
 
-==========================
-Enhancing train-test split
-==========================
+================
+Train-test split
+================
 
 This example illustrates the motivation and the use of skore's
 :func:`skore.train_test_split` to get assistance when developing ML/DS projects.

diff --git a/examples/track/README.txt b/examples/track/README.txt
diff --git a/sphinx/_static/css/custom.css b/sphinx/_static/css/custom.css
@@ -70,13 +70,20 @@ div.docutils.container.index-box {
     margin-bottom: 1rem;
 }
 
+/* logo at the top left (not just the landing page) */
 .logo {
-    max-width: 150px;
+    max-width: 100px;
+    height: auto;
+}
+
+/* logo for the landing page */
+.logo-landing {
+    max-width: 200px;
     height: auto;
 }
 
 .hero-title {
-    color: #DA7007; /* Darker text color for the title */
+    color: #F68D2E;
     font-family: var(--pst-font-family-heading);
     font-size: 2.5rem;
     margin-bottom: 2rem;

diff --git a/sphinx/conf.py b/sphinx/conf.py
@@ -47,18 +47,23 @@
     "js/sg_plotly_resize.js",
 ]
 
+# list of examples in explicit order
+examples_ordered = [
+    "../examples/getting_started",
+    "../examples/getting_started/plot_quick_start",
+    "../examples/getting_started/plot_skore_product_tour",
+    "../examples/getting_started/plot_working_with_projects",
+    "../examples/getting_started/plot_tracking_items",
+    "../examples/model_evaluation",
+    "../examples/model_evaluation/plot_train_test_split"
+    "../examples/model_evaluation/plot_cross_validate",
+]
+
 # sphinx_gallery options
 sphinx_gallery_conf = {
     "examples_dirs": "../examples",  # path to example scripts
     "gallery_dirs": "auto_examples",  # path to gallery generated output
-    "subsection_order": ExplicitOrder(["../examples/getting_started",
-                                       "../examples/getting_started/plot_getting_started",
-                                       "../examples/track",
-                                       "../examples/track/plot_overview_skore_project",
-                                       "../examples/track/plot_tracking_items",
-                                       "../examples/diagnose",
-                                       "../examples/diagnose/plot_cross_validate",
-                                       "../examples/diagnose/plot_train_test_split"]),
+    "subsection_order": ExplicitOrder(examples_ordered),
     "within_subsection_order": "FileNameSortKey",  # See https://sphinx-gallery.github.io/stable/configuration.html#sorting-gallery-examples for alternatives
     "show_memory": False,
     "write_computation_times": False,
@@ -101,21 +106,18 @@
     # In particular, "**" specifies the default for all pages
     # Use :html_theme.sidebar_secondary.remove: for file-wide removal
     "secondary_sidebar_items": {
-        "**": ["page-toc", "sourcelink", "sg_download_links", "sg_launcher_links"]
+        "**": ["page-toc", "sourcelink", "sg_download_links", "sg_launcher_links"],
+        "index": [], # hide secondary sidebar items for the landing page
+        "install": [],
     },
     "external_links": [
         {
             "url": "https://probabl.ai",
-            "name": "Probabl website",
+            "name": "Probabl",
         },
     ],
     "header_links_before_dropdown": 5,
     "icon_links": [
-        {
-            "name": "Twitter",
-            "url": "https://x.com/probabl_ai",
-            "icon": "fa-brands fa-twitter",
-        },
         {
             "name": "GitHub",
             "url": "https://github.com/probabl-ai/skore/",
@@ -126,6 +128,26 @@
             "url": "https://discord.gg/scBZerAGwW",
             "icon": "fa-brands fa-discord",
         },
+        {
+            "name": "YouTube",
+            "url": "https://www.youtube.com/@probabl_ai",
+            "icon": "fa-brands fa-youtube",
+        },
+        {
+            "name": "LinkedIn",
+            "url": "https://www.linkedin.com/company/probabl/",
+            "icon": "fa-brands fa-linkedin-in",
+        },
+        {
+            "name": "Bluesky",
+            "url": "https://bsky.app/profile/probabl.ai",
+            "icon": "fa-brands fa-bluesky",
+        },
+        {
+            "name": "X (ex-Twitter)",
+            "url": "https://x.com/probabl_ai",
+            "icon": "fa-brands fa-x-twitter",
+        },
     ],
     "switcher": {
         "json_url": "https://skore.probabl.ai/versions.json",
@@ -148,6 +170,7 @@
 
 # Sphinx remove the sidebar from some pages
 html_sidebars = {
+    "index": [],
     "install": [],
     "contributing_link": [],
 }