ENH Adds ability to create table of contents

docs/changes.rst

@@ -14,6 +14,8 @@ v0.6
 - Added tabular regression example. :pr: `254` by `Thomas Lazarus`
 - All public ``scipy.special`` ufuncs (Universal Functions) are trusted by default
   by :func:`.io.load`. :pr:`295` by :user:`Omar Arab Oghli <omar-araboghli>`.
+- Add :func:`.Card.create_toc` to create a table of contents for the model card in
+  markdown format. :pr:`305` by :user:`Thomas Lazarus <lazarust>`.
 - Add example of using model card without the skops template. :pr:`291` by
   `Benjamin Bossan`_.
 - Fix: skops persistence now also works with many functions from the

skops/card/_model_card.py

@@ -1315,3 +1315,59 @@ def render(self) -> str:
             sections inserted.
         """
         return "\n".join(self._generate_card())
+
+    def _iterate_key_section_content(
+        self,
+        data: dict[str, Section],
+        level: int = 0,
+    ):
+        """Iterate through the key sections and yield the title and level.
+
+        Parameters
+        ----------
+        data : dict[str, Section]
+            The card data to iterate through. This is usually the sections and subsections.
+
+        level : int, optional
+            The level of the section, by default 0. This keeps track of subsections.
+
+        Returns
+        -------
+        table_of_contents : str
+            Example:
+                - Model description
+                    - Intended uses & limitations
+                    - Training Procedure
+                        - Hyperparameters
+                        - Model Plot
+                    - Evaluation Results
+                - How to Get Started with the Model
+                - Model Card Authors
+                - Model Card Contact
+        """
+        for key, val in data.items():
+            if not getattr(val, "visible", True):
+                continue
+
+            title = val.title
+            yield title, level
+
+            if val.subsections:
+                yield from self._iterate_key_section_content(
+                    val.subsections,
+                    level=level + 1,
+                )
+
+    def get_toc(self) -> str:
+        """Create a table of contents for the model card.
+
+        Returns
+        -------
+        toc : str
+            The table of contents for the model card formatted as a markdown string.
+        """
+        sections = []
+        for title, level in self._iterate_key_section_content(self._data):
+            sections.append(f"{'  ' * level}- {title}")
+
+        return "\n".join(sections)

skops/card/tests/test_card.py

@@ -1593,3 +1593,50 @@ def test_visibility_with_card_save(self, card):
             "Jane Doe"
         )
         assert loaded.strip() == expected
+
+
+class TestCardTableOfContents:
+    @pytest.fixture
+    def card(self):
+        model = LinearRegression()
+        card = Card(model=model)
+        card.add_model_plot()
+        card.add_hyperparams()
+        card.add_metrics(accuracy=0.1)
+        card.add_get_started_code()
+        return card
+
+    def test_toc(self, card):
+        toc = card.get_toc()
+        exptected_toc = [
+            "- Model description",
+            "  - Intended uses & limitations",
+            "  - Training Procedure",
+            "    - Hyperparameters",
+            "    - Model Plot",
+            "  - Evaluation Results",
+            "- How to Get Started with the Model",
+            "- Model Card Authors",
+            "- Model Card Contact",
+            "- Citation",
+        ]
+
+        assert toc == "\n".join(exptected_toc)
+
+    def test_toc_with_invisible_section(self, card):
+        section = card.select("Citation")
+        section.visible = False
+        toc = card.get_toc()
+        exptected_toc = [
+            "- Model description",
+            "  - Intended uses & limitations",
+            "  - Training Procedure",
+            "    - Hyperparameters",
+            "    - Model Plot",
+            "  - Evaluation Results",
+            "- How to Get Started with the Model",
+            "- Model Card Authors",
+            "- Model Card Contact",
+        ]
+
+        assert toc == "\n".join(exptected_toc)