Restructure Documentation

build_scripts/copy_changelog.py

@@ -9,7 +9,7 @@
 root_dir = Path(__file__).parent.parent
 docs_dir = root_dir / "docs"
 changelog_file = root_dir / "CHANGELOG.md"
-target_filepath = docs_dir / changelog_file.name
+target_filepath = docs_dir / "changelog.md"
 
 
 @mkdocs.plugins.event_priority(100)

build_scripts/copy_contributing_guide.py

@@ -9,7 +9,7 @@
 root_dir = Path(__file__).parent.parent
 docs_dir = root_dir / "docs"
 contributing_file = root_dir / "CONTRIBUTING.md"
-target_filepath = docs_dir / contributing_file.name
+target_filepath = docs_dir / "development_guidelines.md"
 
 
 @mkdocs.plugins.event_priority(100)

build_scripts/generate_api_docs.py

@@ -3,12 +3,15 @@
 
 import mkdocs_gen_files
 
+SOURCE_PATH = "src"
+API_REFERENCE_PATH = "api/development/reference"
+
 nav = mkdocs_gen_files.Nav()
-root = Path("src")  # / Path("pydvl")
+root = Path(SOURCE_PATH)
 for path in sorted(root.rglob("*.py")):
     module_path = path.relative_to(root).with_suffix("")
     doc_path = path.relative_to(root).with_suffix(".md")
-    full_doc_path = Path("api") / doc_path
+    full_doc_path = Path(API_REFERENCE_PATH) / doc_path
     parts = tuple(module_path.parts)
 
     if parts[-1] == "__init__":

docs/.gitignore

@@ -5,6 +5,8 @@
 pydvl/*
 !pydvl/index.rst
 
-# Changelog
+# Files copied during documentation build
 CHANGELOG.md
-CONTRIBUTING.md
+changelog.md
+CONTRIBUTING.md
+development_guidelines.md

docs/api/development/index.md

@@ -0,0 +1,31 @@
+---
+title: Development
+alias:
+  name: development
+  title: Development
+---
+
+<div class="grid cards" markdown>
+
+-   :fontawesome-solid-code:{ .lg .middle }
+    [__API Reference__](reference/pydvl)
+
+    ---
+    Full documentation of the API
+
+
+-   :fontawesome-solid-timeline:{ .lg .middle }
+    [__Changelog__](/changelog)
+
+    ---
+    Chronologically ordered list of notable changes for each version
+    of pyDVL.
+
+
+-   :fontawesome-solid-screwdriver-wrench:{ .lg .middle }
+    [__Development Guidelines__](/development_guidelines)
+
+    ---
+    Development guidelines
+
+</div>

docs/api/index.md

@@ -0,0 +1,22 @@
+---
+title: API
+alias:
+  name: api
+  title: API
+---
+
+<div class="grid cards" markdown>
+
+-   :fontawesome-solid-code:{ .lg .middle }
+    [[user-api|__User API__]]
+
+    ---
+    Documentation of the User API
+
+-   :fontawesome-solid-screwdriver-wrench:{ .lg .middle }
+    [[development|__Development__]]
+
+    ---
+    Full API Documentation, Changelog and Guidelines
+
+</div>

docs/api/user-api/index.md

@@ -0,0 +1,10 @@
+---
+title: User API
+alias:
+  name: user-api
+  title: User API
+---
+
+::: pydvl.value.shapley.montecarlo.permutation_montecarlo_shapley
+
+::: pydvl.influence.torch.DirectInfluence

docs/javascripts/mathjax.js → docs/assets/js/mathjax.js

@@ -12,5 +12,8 @@ window.MathJax = {
 };
 
 document$.subscribe(() => {
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
   MathJax.typesetPromise()
 })

docs/how-to-guides/index.md

@@ -0,0 +1,7 @@
+---
+title: How-to Guides
+alias:
+  name: how-to-guides
+  title: How-to Guides
+---
+

docs/index.md

@@ -18,42 +18,26 @@ If you're a first time user of pyDVL, we recommend you to go through
     [[getting-started|__Getting started__]]
 
     ---
-    Steps to install and requirements
+    New users of pyDVL should read this first.
 
--   :fontawesome-regular-images:{ .lg .middle }
-    [[examples|__Example gallery__]]
-
-    ---
-
-    Notebooks with worked-out examples of data valuation and influence functions
-
--   :fontawesome-solid-scale-unbalanced:{ .lg .middle }
-    [[data-valuation|__Data valuation__]]
-
-    ---
-
-    Basics of data valuation and description of the main algorithms
-
--   :fontawesome-solid-scale-unbalanced-flip:{ .lg .middle } 
-    [[influence-function|__Influence Function__]]
+-   :fontawesome-solid-book-open:{ .lg .middle }
+    [[how-to-guides|__How-to Guides__]]
 
     ---
+    Detailed instructions for specific and advanced tasks.
 
-    An introduction to the influence function and its computation with pyDVL
-
--   :material-cog:{ .lg .middle }
-    [[methods|__Supported methods__]]
+-   :fontawesome-solid-book-atlas:{ .lg .middle }
+    [[methods|__Methods__]]
 
     ---
+    Background information and explanations of data valuation
+    and influence function methods.
 
-    List of all methods implemented with references.
-
-
--   :fontawesome-regular-file-code:{ .lg .middle }
-    [__API Reference__](api/pydvl/)
-
+-   :fontawesome-regular-images:{ .lg .middle }
+    [[tutorials|__Tutorials__]]
+
     ---
-
-    Full documentation of the API
+    Worked-out examples of data valuation and influence function methods
+    showing how to do certain tasks using pyDVL.
 
 </div>

docs/influence/index.md

@@ -30,6 +30,29 @@ pyDVL implements several methods for the efficient computation of the IF for
 machine learning. In the examples we document some of the difficulties that can
 arise when using the IF.
 
+We currently implement the following methods:
+
+- [**CG Influence**][pydvl.influence.torch.CgInfluence].
+  [@koh_understanding_2017].
+
+- [**Direct Influence**][pydvl.influence.torch.DirectInfluence]
+  [@koh_understanding_2017].
+
+- [**LiSSA**][pydvl.influence.torch.LissaInfluence]
+  [@agarwal_secondorder_2017].
+
+- [**Arnoldi Influence**][pydvl.influence.torch.ArnoldiInfluence]
+  [@schioppa_scaling_2022].
+
+- [**EKFAC Influence**][pydvl.influence.torch.EkfacInfluence]
+  [@george_fast_2018;@martens_optimizing_2015].
+
+- [**Nyström Influence**][pydvl.influence.torch.NystroemSketchInfluence], based
+  on the ideas in [@hataya_nystrom_2023] for bi-level optimization.
+
+- [**Inverse-harmonic-mean Influence**][pydvl.influence.torch.InverseHarmonicMeanInfluence]
+  [@kwon_datainf_2023].
+
 ## Construction
 
 First introduced in the context of robust statistics in [@hampel_influence_1974],

docs/methods/index.md

@@ -0,0 +1,24 @@
+---
+title: Methods
+alias:
+  name: methods
+  title: Methods
+---
+
+<div class="grid cards" markdown>
+
+-   :fontawesome-solid-scale-unbalanced:{ .lg .middle }
+    [[data-valuation|__Data valuation__]]
+
+    ---
+
+    Basics of data valuation and description of the main algorithms
+
+-   :fontawesome-solid-scale-unbalanced-flip:{ .lg .middle } 
+    [[influence-function|__Influence Function__]]
+
+    ---
+
+    An introduction to the influence function and its computation with pyDVL
+
+</div>

docs/tutorials/index.md

@@ -0,0 +1,6 @@
+---
+title: Tutorials
+alias:
+  name: tutorials
+  text: Tutorials
+---

docs/value/index.md

@@ -50,6 +50,43 @@ influence-based and intrinsic. As of v0.8.1 pyDVL supports the first two. Here,
 we focus on game-theoretic concepts and refer to the main documentation on the
 [influence funtion][the-influence-function] for the second.
 
+We currently implement the following methods:
+
+- [**LOO**][pydvl.value.loo.compute_loo].
+
+- [**Permutation Shapley**][pydvl.value.shapley.montecarlo.permutation_montecarlo_shapley]
+  (also called **ApproxShapley**) [@castro_polynomial_2009].
+
+- [**TMCS**][pydvl.value.shapley.compute_shapley_values]
+  [@ghorbani_data_2019].
+
+- [**Data Banzhaf**][pydvl.value.semivalues.compute_banzhaf_semivalues]
+  [@wang_data_2022].
+
+- [**Beta Shapley**][pydvl.value.semivalues.compute_beta_shapley_semivalues]
+  [@kwon_beta_2022].
+
+- [**CS-Shapley**][pydvl.value.shapley.classwise.compute_classwise_shapley_values]
+  [@schoch_csshapley_2022].
+
+- [**Least Core**][pydvl.value.least_core.montecarlo.montecarlo_least_core]
+  [@yan_if_2021].
+
+- [**Owen Sampling**][pydvl.value.shapley.owen.owen_sampling_shapley]
+  [@okhrati_multilinear_2021].
+
+- [**Data Utility Learning**][pydvl.utils.utility.DataUtilityLearning]
+  [@wang_improving_2022].
+
+- [**kNN-Shapley**][pydvl.value.shapley.knn.knn_shapley]
+  [@jia_efficient_2019a].
+
+- [**Group Testing**][pydvl.value.shapley.gt.group_testing_shapley]
+  [@jia_efficient_2019]
+
+- [**Data-OOB**][pydvl.value.oob.compute_data_oob]
+  [@kwon_dataoob_2023].
+
 ## Game theoretical methods
 
 The main contenders in game-theoretic approaches are [Shapley