diff --git a/sphinx/conf.py b/sphinx/conf.py index 46d3eac916..5868235698 100644 --- a/sphinx/conf.py +++ b/sphinx/conf.py @@ -37,6 +37,7 @@ "sphinx_copybutton", "sphinx_tabs.tabs", "sphinx_autosummary_accessors", + "autoshortsummary", ] exclude_patterns = ["build", "Thumbs.db", ".DS_Store"] diff --git a/sphinx/reference/index.rst b/sphinx/reference/index.rst index 223578a609..096436509f 100644 --- a/sphinx/reference/index.rst +++ b/sphinx/reference/index.rst @@ -11,7 +11,27 @@ This page lists all the public functions and classes of the skore package. .. toctree:: :maxdepth: 2 + :hidden: Managing a project ML Assistance Utilities + +.. currentmodule:: skore + +.. list-table:: + :header-rows: 1 + :class: apisearch-table + + * - Object + - Description + * - :obj:`EstimatorReport` + - .. div:: sk-apisearch-desc + .. autoshortsummary:: EstimatorReport + .. div:: caption + :mod:`skore` + * - :obj:`EstimatorReport.metrics.accuracy` + - .. div:: sk-apisearch-desc + .. autoshortsummary:: EstimatorReport.metrics.accuracy + .. div:: caption + :mod:`skore` diff --git a/sphinx/sphinxext/autoshortsummary.py b/sphinx/sphinxext/autoshortsummary.py new file mode 100644 index 0000000000..22fbdcd39b --- /dev/null +++ b/sphinx/sphinxext/autoshortsummary.py @@ -0,0 +1,54 @@ +# Adapted from scikit-learn +from sphinx.ext.autodoc import ModuleLevelDocumenter + + +class ShortSummaryDocumenter(ModuleLevelDocumenter): + """An autodocumenter that only renders the short summary of the object.""" + + # Defines the usage: .. autoshortsummary:: {{ object }} + objtype = "shortsummary" + + # Disable content indentation + content_indent = "" + + # Avoid being selected as the default documenter for some objects, because we are + # returning `can_document_member` as True for all objects + priority = -99 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + """Allow documenting any object.""" + return True + + def get_object_members(self, want_all): + """Document no members.""" + return (False, []) + + def add_directive_header(self, sig): + """Override default behavior to add no directive header or options.""" + pass + + def add_content(self, more_content): + """Override default behavior to add only the first line of the docstring. + + Modified based on the part of processing docstrings in the original + implementation of this method. + + https://github.com/sphinx-doc/sphinx/blob/faa33a53a389f6f8bc1f6ae97d6015fa92393c4a/sphinx/ext/autodoc/__init__.py#L609-L622 + """ + sourcename = self.get_sourcename() + docstrings = self.get_doc() + + if docstrings is not None: + if not docstrings: + docstrings.append([]) + # Get the first non-empty line of the processed docstring; this could lead + # to unexpected results if the object does not have a short summary line. + short_summary = next( + (s for s in self.process_doc(docstrings) if s), "" + ) + self.add_line(short_summary, sourcename, 0) + + +def setup(app): + app.add_autodocumenter(ShortSummaryDocumenter)