Doc improvements

.gitattributes

@@ -1 +1,2 @@
 notebooks/*.ipynb -linguist-detectable
+*.png filter=lfs diff=lfs merge=lfs -text

CHANGELOG.md

@@ -22,8 +22,10 @@
   are available through `pydvl.utils.cache`
   [PR #509](https://github.com/aai-institute/pyDVL/pull/509)  
 
-### Miscellaneous
+### Changed
 
+- Improvements to documentation: fixes, links, text, example gallery and more
+  [PR #532](https://github.com/aai-institute/pyDVL/pull/532)
 - Bump versions of CI actions to avoid warnings [PR #502](https://github.com/aai-institute/pyDVL/pull/502)
 - Add Python Version 3.11 to supported versions [PR #510](https://github.com/aai-institute/pyDVL/pull/510)
 - Documentation improvements and cleanup [PR #521](https://github.com/aai-institute/pyDVL/pull/521) [PR #522](https://github.com/aai-institute/pyDVL/pull/522)
@@ -49,7 +51,7 @@
 - Fixed bug with checking for converged values in semivalues
   [PR #341](https://github.com/appliedAI-Initiative/pyDVL/pull/341)
 
-### Docs
+### Changed
 
 - Add applications of data valuation section, display examples more prominently,
   make all sections visible in table of contents, use mkdocs material cards
@@ -105,6 +107,11 @@
 - Faster semi-value computation with per-index check of stopping criteria (optional)
   [PR #437](https://github.com/aai-institute/pyDVL/pull/437)
 
+### Fixed
+
+- Fix initialization of `data_names` in `ValuationResult.zeros()`
+  [PR #443](https://github.com/aai-institute/pyDVL/pull/443)
+
 ### Changed
 
 - No longer using docker within tests to start a memcached server
@@ -116,12 +123,6 @@
 - Refactoring of parallel module. Old imports will stop working in v0.9.0
   [PR #421](https://github.com/aai-institute/pyDVL/pull/421)
 
-### Fixed
-
-- Fix initialization of `data_names` in `ValuationResult.zeros()`
-  [PR #443](https://github.com/aai-institute/pyDVL/pull/443)
-
-
 ## 0.7.0 - 📚🆕 Documentation and IF overhaul, new methods and bug fixes 💥🐞
 
 This is our first β release! We have worked hard to deliver improvements across

CONTRIBUTING.md

@@ -11,7 +11,7 @@ improvements to the currently implemented methods and other ideas. Please open a
 ticket with yours.
 
 If you are interested in setting up a similar project, consider the template 
-[pymetrius](https://github.com/aai-institute/pymetrius).
+[pymetrius](https://github.com/appliedAI-Initiative/pymetrius).
 
 ## Local development
 
@@ -239,7 +239,8 @@ This applies a simple CSS-filter to the output image of the cell.
 ## Documentation
 
 API documentation and examples from notebooks are built with
-[mkdocs](https://www.mkdocs.org/), with versioning handled by
+[mkdocs](https://www.mkdocs.org/), using a number of plugins, including
+[mkdoctrings](https://mkdocstrings.github.io/), with versioning handled by
 [mike](https://github.com/jimporter/mike).
 
 Notebooks are an integral part of the documentation as well, please read
@@ -272,19 +273,57 @@ pages are explicitly listed and manually arranged in the `nav` section of the
 configuration.
 
 
+### Creating stable references for autorefs
+
+mkdocstrings includes the plugin
+[autorefs](https://github.com/mkdocstrings/autorefs) to enable automatic linking
+across pages with e.g. `[a link][to-something]`. Anchors are autogenerated
+from section titles, and are not guaranteed to be unique. In order to ensure
+that a link will remain valid, add a custom anchor to the section title:
+
+```markdown
+## Some section { #permanent-anchor-to-some-section }
+```
+
+(note the space after the opening brace). You can then refer to it within
+another markdown file with `[Some section][permanent-anchor-to-some-section]`.
+
+
 ### Using bibliography
 
-Bibliographic citations are managed with the plugins 
-[mkdocs-bibtex]() and [...][].
-To enter a citation first add the entry to `docs/pydvl.bib`. For team
-contributor this should be an export of the Zotero folder `software/pydvl` in
-the [TransferLab Zotero library](https://www.zotero.org/groups/2703043/transferlab/library).
-All other contributors just add the bibtex data, and a maintainer will add it to
-the group library upon merging.
+Bibliographic citations are managed with the plugin
+[mkdocs-bibtex](https://github.com/shyamd/mkdocs-bibtex/). To enter a citation
+first add the entry to `docs/pydvl.bib`. For team contributor this should be an
+export of the Zotero folder `software/pydvl` in the [TransferLab Zotero
+library](https://www.zotero.org/groups/2703043/transferlab/library). All other
+contributors just add the bibtex data, and a maintainer will add it to the group
+library upon merging.
 
-To add a citation inside a module or function's docstring, use the notation
-`[@citekey]`. A references section is automatically added at the bottom of each
-module's auto-generated documentation.
+To add a citation inside a markdown file, use the notation `[@citekey]`. Alas,
+because of when mkdocs-bibtex enters the pipeline, it won't process docstrings.
+For module documentation, we manually inject html into the markdown files. For
+example, in `pydvl.value.shapley.montecarlo` we have:
+
+```markdown
+"""
+Module docstring...
+
+## References
+
+[^1]: <a name="ghorbani_data_2019"></a>Ghorbani, A., Zou, J., 2019.
+    [Data Shapley: Equitable Valuation of Data for Machine
+    Learning](https://proceedings.mlr.press/v97/ghorbani19c.html).
+    In: Proceedings of the 36th International Conference on Machine Learning,
+    PMLR, pp. 2242–2251.
+"""
+```
+
+and then later in the file, inside a function's docstring:
+
+```markdown
+    This function implements (Ghorbani and Zou, 2019)<sup><a 
+    href="#ghorbani_data_2019">1</a></sup>
+```
 
 ### Writing mathematics
 
@@ -298,18 +337,21 @@ exceptions). For simplicity, declare the string as "raw" with the prefix `r`:
 # This will work
 def f(x: float) -> float:
     r""" Computes 
-    $$ f(x) = \frac{1}{x^2} $
+    $${ f(x) = \frac{1}{x^2} }$$
     """
     return 1/(x*x)
 
-# This throws an obscure sphinx error
+# This throws an obscure error
 def f(x: float) -> float:
     """ Computes 
-    $$ \frac{1}{x^2} $$
+    $$\frac{1}{x^2}$$
     """
     return 1/(x*x)
 ```
 
+Note how there is no space after the dollar signs. This is important! You can
+use braces for legibility like in the first example.
+
 ### Abbreviations
 
 We keep the abbreviations used in the documentation inside the
@@ -498,7 +540,8 @@ readme). In order to do this, simply prefix the commit message with `[skip ci]`.
 The string can be anywhere, but adding it to the beginning of the commit message
 makes it more evident when looking at commits in a PR.
 
-Refer to the official [GitHub documentation](https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs) 
+Refer to the official [GitHub
+documentation](https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs) 
 for more information.
 
 ## Release processes
@@ -578,7 +621,7 @@ create a new release manually by following these steps:
     ```
 7. Delete the release branch if necessary: 
    `git branch -d release/${RELEASE_VERSION}`
-8. Create a Github
+8. Create a GitHub
    [release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release)
    for the created tag.
 9. Pour yourself a cup of coffee, you earned it! :coffee: :sparkles:
@@ -608,8 +651,8 @@ a GitHub release.
 We use [bump2version](https://pypi.org/project/bump2version/) to bump
 the build part of the version number without commiting or tagging the change
 and then publish a package to TestPyPI from CI using Twine. The version
-has the github run number appended. 
+has the GitHub run number appended. 
 
-For more details refer to the
+For more details refer to the files
 [.github/workflows/publish.yaml](.github/workflows/publish.yaml) and
-[.github/workflows/tox.yaml](.github/workflows/tox.yaml) files.
+[.github/workflows/tox.yaml](.github/workflows/tox.yaml).

README.md

@@ -82,7 +82,7 @@ $ pip install pyDVL[influence]
 ```
 
 For more instructions and information refer to [Installing pyDVL
-](https://pydvl.org/stable/getting-started/installation/) in the
+](https://pydvl.org/stable/getting-started/#installation) in the
 documentation.
 
 # Usage