docs: Document the skore.project.metadata.Metadata class (#1754)

Right now, we don't document `skore.project.metadata.Metadata`.

In short, it means that no one is aware of the API of the output of
`project.reports.metadata()` and what to do with it.

I avoid to list the inherited methods from the pandas dataframe since
the import in this case would not work. Instead I modify the
documentation to refer to the original documentation in the docstring.

Author: glemaitre

skore/src/skore/project/metadata.py

@@ -18,25 +18,21 @@ class Metadata(DataFrame):
     """
     Metadata and metrics for all reports persisted in a project at a given moment.
 
-    A metadata object is an extended ``pandas.DataFrame``, containing all the metadata
-    and metrics of the reports that have been persisted in a project. It implements a
-    custom HTML representation, that allows user to filter its reports using a parallel
-    coordinates plot. In a Jupyter Notebook, this representation automatically replaces
-    the standard ``pandas.DataFrame`` one and displays an interactive plot.
+    A metadata object is an extended :class:`pandas.DataFrame`, containing all the
+    metadata and metrics of the reports that have been persisted in a project. It
+    implements a custom HTML representation, that allows user to filter its reports
+    using a parallel coordinates plot. In a Jupyter Notebook, this representation
+    automatically replaces the standard :class:`pandas.DataFrame` one and displays an
+    interactive plot.
 
     The parallel coordinates plot is interactive, such the user can select a filter path
     and retrieve the corresponding reports.
 
     Outside a Jupyter Notebook, the metadata object can be used as a standard
-    ``pandas.DataFrame`` object. This means that it can be questioned, divided etc.,
-    using the standard ``pandas.DataFrame`` functions.
+    :class:`pandas.DataFrame` object. This means that it can be questioned, divided
+    etc., using the standard :class:`pandas.DataFrame` functions.
 
-    Methods
-    -------
-    reports(filter=True) -> list[skore.sklearn.EstimatorReport]
-        Return the reports referenced by the metadata object from the project.
-        If a query string selection exists, it will be automatically applied before, to
-        filter the reports to return. Otherwise, returns all reports.
+    Refer to :class:`pandas.DataFrame` for the standard methods and attributes.
     """
 
     _metadata = ["project"]
@@ -54,7 +50,7 @@ def factory(project, /):
         Notes
         -----
         This function is not intended for direct use. Instead simply use the accessor
-        ``skore.Project.reports.metadata``.
+        :meth:`skore.Project.reports.metadata`.
         """
         metadata = DataFrame(project.reports.metadata(), copy=False)
 

sphinx/_templates/class_without_inherited_members.rst

@@ -0,0 +1,8 @@
+{{ objname | escape | underline(line="=") }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :no-inherited-members:
+   :special-members: __call__

sphinx/reference/project.rst

@@ -3,7 +3,10 @@ Managing a project
 
 .. currentmodule:: skore
 
-These functions and classes are meant for managing a Project and its reports.
+Skore project
+^^^^^^^^^^^^^
+
+These functions and classes are meant for managing a `Project` and its reports.
 
 .. autosummary::
     :toctree: api/
@@ -33,3 +36,27 @@ These functions and classes are meant for managing a Project and its reports.
 
    Project.reports.get
    Project.reports.metadata
+
+Skore project's metadata
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+When calling :meth:`Project.reports.metadata`, a
+:class:`~skore.project.metadata.Metadata` object is returned. This object is a
+:class:`pandas.DataFrame` with a specific HTML representation to allow you filter and
+retrieve the reports.
+
+.. autosummary::
+   :toctree: api/
+   :template: class_without_inherited_members.rst
+
+   project.metadata.Metadata
+
+.. autosummary::
+   :toctree: api/
+   :template: class_methods_no_index.rst
+
+   project.metadata.Metadata.reports
+
+.. note::
+   This class :class:`~skore.project.metadata.Metadata` is not meant to be used
+   directly. Instead, use the accessor :meth:`Project.reports.metadata`.