Skip to content

Commit 2ccfeb5

Browse files
mmschlkmmschlk
authored
Work on Docs to remove warnings. (#495)
* docs: fix duplicate-label warnings via autosectionlabel_prefix_document Setting autosectionlabel_prefix_document = True prefixes every auto-generated section label with its document path, preventing collisions when multiple notebooks share identical headings like "General Use" or "Feature Names". Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: fix all remaining Sphinx warnings Three root causes resolved: - language_model_game.ipynb was doubly-wrapped: the file contained a single raw cell whose source was the entire notebook JSON. Unwrapped to the correct 31-cell notebook, fixing 129 repeated toc.no_title warnings (nbsphinx fired once per output page because no title was visible). - Deleted orphaned api/shapiq.imputer.conditional_imputer.rst which referenced a module that no longer exists, causing an autodoc import failure and a "document not in toctree" warning. - Added examples/GALLERY_HEADER.rst to exclude_patterns so sphinx- gallery's header file does not produce a "document not in toctree" warning (sphinx-gallery includes it internally via auto_examples/). The docs now build with -W --keep-going without any warnings. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * updated docs to reduce warning count * updated docs to reduce warning count * ignore duplicate object warning * supress ref.python warning * updated api.rst * added numpy to build requires Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * updated AGENTS.md to be more helpful. Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * github workflows Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * wrote a short description about how to create releases Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * add a test to find missing objects in __all__ Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * updated conf.py to include only __all__ members Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * updated api references Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * updated api references Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * updated api references Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * updated citations and approximators files Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * refactored docs generation Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * fix docs Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * updated docs dependency Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> * updated CI Signed-off-by: Maximilian <maximilian.muschalik@gmail.com> --------- Signed-off-by: Maximilian <maximilian.muschalik@gmail.com>
1 parent 4d9ae70 commit 2ccfeb5

59 files changed

Lines changed: 1338 additions & 1138 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ jobs:
177177
- name: Install dependencies
178178
run: uv sync --no-dev --group docs
179179
- name: Build documentation
180-
run: uv run --no-sync sphinx-build --keep-going -b html docs/source docs/build/html
180+
run: uv run --no-sync sphinx-build -W --keep-going -b html docs/source docs/build/html
181181
# ----------------------------------------------------------------------------------------------
182182
# Code Coverage
183183
# ----------------------------------------------------------------------------------------------

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,8 @@ instance/
7575

7676
# Sphinx documentation
7777
docs/_build/docs/build/
78-
docs/source/api/
78+
docs/source/api/shapiq*
79+
docs/source/api/*/
7980

8081
# PyBuilder
8182
.pybuilder/
@@ -192,5 +193,6 @@ src/shapiq/_version.py
192193
# Documentation build artifacts
193194
docs/source/auto_examples/
194195
docs/source/sg_execution_times.rst
196+
docs/source/generated/
195197

196198
.claude

‎AGENTS.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,16 @@
11
# AGENTS.md
22

33
This role of this file is to describe common mistakes and confusion points that agents might encounter as they work in this project. If you ever encounter something in the project that surprises you, please alert the developer working with you and indicate that this is the case in the Agent.md file to help prevent future agents from having the same issue.
4+
5+
6+
## Commands to interact with the codebase which you should run:
7+
8+
### Build Docs (only use this command verbatim from the project root)
9+
```bash
10+
rm -rf docs/source/generated && uv run sphinx-build -b html docs/source docs/build/html
11+
```
12+
13+
### Run Pre-commit (takes only 3s)
14+
```bash
15+
uv run pre-commit run --all-files
16+
```

‎CLAUDE.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# AGENTS.md
2+
3+
This role of this file is to describe common mistakes and confusion points that agents might encounter as they work in this project. If you ever encounter something in the project that surprises you, please alert the developer working with you and indicate that this is the case in the Agent.md file to help prevent future agents from having the same issue.
4+
5+
6+
## Commands to interact with the codebase which you should run:
7+
8+
### Build Docs (only use this command verbatim from the project root)
9+
```bash
10+
rm -rf docs/source/generated && uv run sphinx-build -b html docs/source docs/build/html
11+
```
12+
13+
### Run Pre-commit (takes only 3s)
14+
```bash
15+
uv run pre-commit run --all-files
16+
```

‎docs/source/_templates/autosummary/class.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. autoclass:: {{ objname }}
6+
:show-inheritance:

‎docs/source/_templates/autosummary/module.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{{ fullname | escape | underline }}
2+
3+
.. automodule:: {{ fullname }}
4+
:no-members:
5+
6+
{% if classes %}
7+
.. rubric:: Classes
8+
9+
.. autosummary::
10+
:toctree:
11+
:nosignatures:
12+
{% for item in classes %}
13+
{{ item }}
14+
{%- endfor %}
15+
{% endif %}
16+
17+
{% if functions %}
18+
.. rubric:: Functions
19+
20+
.. autosummary::
21+
:toctree:
22+
:nosignatures:
23+
{% for item in functions %}
24+
{{ item }}
25+
{%- endfor %}
26+
{% endif %}
27+
28+
{% if attributes %}
29+
.. rubric:: Module Attributes
30+
31+
.. autosummary::
32+
:toctree:
33+
:nosignatures:
34+
{% for item in attributes %}
35+
{{ item }}
36+
{%- endfor %}
37+
{% endif %}

‎docs/source/api.rst‎

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎docs/source/api_reference.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. _api_reference:
2+
3+
=============
4+
API Reference
5+
=============
6+
7+
This is the API reference for the ``shapiq`` package.
8+
9+
.. autosummary::
10+
:toctree: generated/
11+
:nosignatures:
12+
13+
shapiq.interaction_values
14+
shapiq.game
15+
shapiq.explainer
16+
shapiq.approximator
17+
shapiq.imputer
18+
shapiq.game_theory
19+
shapiq.plot
20+
shapiq.datasets
21+
shapiq.utils
22+
shapiq.tree

‎docs/source/conf.py‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,11 +71,16 @@
7171
".DS_Store",
7272
"**.ipynb_checkpoints",
7373
"auto_examples/**.ipynb",
74+
# sphinx-gallery includes this file internally; exclude to avoid toctree warning
75+
"examples/GALLERY_HEADER.rst",
76+
# stale sphinx-gallery artifact at source root (real copy lives in auto_examples/)
77+
"sg_execution_times.rst",
7478
]
7579
bibtex_bibfiles = ["references.bib"]
7680
bibtex_default_style = (
7781
"alpha" # set to alpha to not confuse references the docs with the footcites in docstrings.
7882
)
83+
bibtex_reference_style = "author_year"
7984

8085
source_suffix = {
8186
".rst": "restructuredtext",
@@ -88,6 +93,7 @@
8893
"scipy": ("https://docs.scipy.org/doc/scipy", None),
8994
"matplotlib": ("https://matplotlib.org/stable", None),
9095
"PIL": ("https://pillow.readthedocs.io/en/stable/", None),
96+
"sklearn": ("https://scikit-learn.org/stable", None),
9197
}
9298

9399
# -- Options for HTML output -----------------------------------------------------------------------
@@ -116,11 +122,23 @@
116122
],
117123
}
118124

125+
# -- Autosectionlabel -----------------------------------------------------------------------------
126+
# Prefix labels with the document path to avoid collisions when multiple documents
127+
# share identical section headings (e.g. "General Use", "Feature Names").
128+
autosectionlabel_prefix_document = True
129+
130+
# -- Napoleon (Google-style docstrings) ------------------------------------------------------------
131+
napoleon_google_docstring = True
132+
napoleon_numpy_docstring = False
133+
napoleon_use_ivar = True
134+
119135
# -- Autodoc ---------------------------------------------------------------------------------------
120136
autosummary_generate = True
137+
autosummary_ignore_module_all = False
121138
autodoc_default_options = {
122139
"show-inheritance": True,
123140
"members": True,
141+
"private-members": False,
124142
"member-order": "groupwise",
125143
"special-members": "__call__",
126144
"undoc-members": True,
@@ -129,6 +147,12 @@
129147
autoclass_content = "both"
130148
autodoc_inherit_docstrings = True
131149
autodoc_member_order = "groupwise"
150+
autodoc_typehints = "both"
151+
152+
# -- Suppress warnings -----------------------------------------------------------------------------
153+
suppress_warnings = [
154+
"misc.highlighting_failure", # should be fixed in the future
155+
]
132156

133157
# -- Images ----------------------------------------------------------------------------------------
134158
StandaloneHTMLBuilder.supported_image_types = [

‎docs/source/examples/plot_shapley_values.py‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
"""Computing Shapley Values.
2-
3-
========================
2+
=========================
43
54
A minimal example showing how to compute exact Shapley values for a small
65
cooperative game using :class:`~shapiq.ExactComputer`.
7-
"""
6+
""" # noqa: D205
87

98
from __future__ import annotations
109

0 commit comments

Comments
 (0)