diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index c195471ee..779d96b9b 100644 --- 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 index e604e3ca9..1fa5c1cef 100644 --- 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 index ff8f17b16..493339c20 100644 --- 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 index 9a66a4204..983e231ca 100644 --- 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 new file mode 100644 index 000000000..871de9453 --- /dev/null +++ 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/examples/getting_started/plot_getting_started.py b/examples/getting_started/plot_skore_product_tour.py similarity index 97% rename from examples/getting_started/plot_getting_started.py rename to examples/getting_started/plot_skore_product_tour.py index d27f11b6b..1002db781 100644 --- a/examples/getting_started/plot_getting_started.py +++ b/examples/getting_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 b/examples/getting_started/plot_tracking_items.py similarity index 92% rename from examples/track/plot_tracking_items.py rename to examples/getting_started/plot_tracking_items.py index f90a4df00..c03c6590b 100644 --- a/examples/track/plot_tracking_items.py +++ b/examples/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/examples/track/plot_overview_skore_project.py b/examples/getting_started/plot_working_with_projects.py similarity index 97% rename from examples/track/plot_overview_skore_project.py rename to examples/getting_started/plot_working_with_projects.py index 3e146026f..880b3ac7e 100644 --- a/examples/track/plot_overview_skore_project.py +++ b/examples/getting_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 b/examples/model_evaluation/README.txt similarity index 79% rename from examples/diagnose/README.txt rename to examples/model_evaluation/README.txt index f90588b79..327af82b9 100644 --- a/examples/diagnose/README.txt +++ b/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 b/examples/model_evaluation/plot_cross_validate.py similarity index 98% rename from examples/diagnose/plot_cross_validate.py rename to examples/model_evaluation/plot_cross_validate.py index 11398e18f..d298538ef 100644 --- a/examples/diagnose/plot_cross_validate.py +++ b/examples/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 b/examples/model_evaluation/plot_train_test_split.py similarity index 98% rename from examples/diagnose/plot_train_test_split.py rename to examples/model_evaluation/plot_train_test_split.py index e6c571b47..8ade0f3ac 100644 --- a/examples/diagnose/plot_train_test_split.py +++ b/examples/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 deleted file mode 100644 index c336d36c2..000000000 --- a/examples/track/README.txt +++ /dev/null @@ -1,4 +0,0 @@ -Track ------ - -These examples illustrate the skore Project and UI. diff --git a/sphinx/_static/css/custom.css b/sphinx/_static/css/custom.css index 7d19c2363..7941afd29 100644 --- 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 index 327b7ab1a..b22954ba3 100644 --- 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": [], } diff --git a/sphinx/index.rst b/sphinx/index.rst index 848ab3de8..2d421bba3 100644 --- a/sphinx/index.rst +++ b/sphinx/index.rst @@ -5,39 +5,16 @@
- - + skore - Home + skore - Home

The scikit-learn Modeling Companion

Elevate ML Development with Tracking and Built-in Recommended Practices

-**** - -.. image:: https://img.shields.io/pypi/l/skore - :alt: license - -.. image:: https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue?style=flat&logo=python - :alt: python - -.. image:: https://static.pepy.tech/badge/skore/month - :alt: downloads - :target: https://pepy.tech/projects/skore - -.. image:: https://img.shields.io/pypi/v/skore - :alt: pypi - :target: https://pypi.org/project/skore/ - -.. image:: https://github.com/probabl-ai/skore/actions/workflows/ci.yml/badge.svg?event=push - :alt: ci - -.. image:: https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white - :alt: Discord - :target: https://discord.probabl.ai/ - .. admonition:: Where to start? - See our :ref:`example_getting_started` example! + See our :ref:`example_quick_start` page! Why skore? ---------- @@ -52,8 +29,6 @@ updates and new features are on the way as we work toward our vision of becoming comprehensive library for data scientists, supporting every phase of the machine learning lifecycle. -⭐ Support us with a star and spread the word - it means a lot! ⭐ - Key features ------------ @@ -73,6 +48,7 @@ Key features .. currentmodule:: skore | + .. toctree:: :maxdepth: 1 :caption: Contents: diff --git a/sphinx/install.rst b/sphinx/install.rst index e24f93359..f223fab84 100644 --- a/sphinx/install.rst +++ b/sphinx/install.rst @@ -5,54 +5,27 @@ Install .. currentmodule:: skore -.. raw:: html +.. tab-set:: -
+ .. tab-item:: Using pip - + We recommend using a `virtual environment (venv) `_. + You need ``python>=3.9``. -
-
-
+ Then, run: -We recommend using a `virtual environment (venv) `_. -You need ``python>=3.9``. + .. code-block:: bash -Then, run: + pip install -U skore -.. code-block:: bash + You can check skore's latest version on `PyPI `_. - pip install -U skore + .. tab-item:: Using conda -You can check skore's latest version on `PyPI `_. + Skore is available in ``conda-forge``: -.. raw:: html + .. code-block:: bash -
-
-
+ conda install conda-forge::skore -skore is available in ``conda-forge``: - -.. code-block:: bash - - conda install conda-forge::skore - -You can find information on the latest version `here `_. - -.. raw:: html - -
-
-
- -.. admonition:: What's next? - - See our :ref:`example_getting_started` example! \ No newline at end of file + You can find information on the latest version `here `_.