docs: add mkdocs-material site with API reference and GitHub Pages deployment (#16)

[prannoydidymus]

What

Closes #16

Adds a documentation site built with mkdocs-material and mkdocstrings, documents mathematical formulations for each explainer, adds an extending guide and API reference, configures GitHub Pages deployment, and streamlines the README to focus on the quick start.

Why

The README was growing long. A dedicated documentation site separates the quick start from deep method explanations, mathematical details, and the full API reference generated from docstrings.

How

• mkdocs.yml: Configured material theme with MathJax math rendering, code copy buttons, search, and mkdocstrings[python] handler with numpy docstring style.
• Pages:
  • docs/index.md & docs/getting-started.md: Overview and step-by-step tutorial for local and global explanations.
  • docs/methods/: Explainer pages with concise mathematics for coalition (Shapley cooperative games, axioms, sampling), surrogate (local linear model, proximity kernel, weighted Ridge), and permutation (loss drops, smooth log-loss, held-out data).
  • docs/methods/consensus.md: Scale normalization, weighted mean / Borda rank aggregation, and Spearman rank agreement ($\rho$).
  • docs/extending.md: Guide on subclassing BaseExplainer and packaging custom explainers via entry points.
  • docs/api/: API reference pages for auto, explainers, explanation, model, and registry.
  • docs/changelog.md: Embedded changelog.
• Workflows:
  • .github/workflows/docs.yml: Builds and deploys documentation to GitHub Pages on push to main.
  • .github/workflows/ci.yml: Added strict docs build validation (mkdocs build --strict).
• README & CHANGELOG:
  • README.md: Streamlined to keep the quick start and added direct navigation links to the docs site.
  • pyproject.toml: Added docs optional dependencies.
  • CHANGELOG.md: Logged release notes under [Unreleased].

Checklist

• Tests added / updated and pytest passes (91 passed)
• ruff check and ruff format --check pass
• Docs / README / CHANGELOG updated where relevant
• Randomness goes through self.rng (reproducible with random_state)

[prannoydidymus]

The work did take a lot of time and helps from various sources and I may be wrong in things that I have done but do review them and comment back if there is any error.

[prannoydidymus]

Hello, is it accepted or changes needed ?

[adaumsilva]

Thanks for adding the documentation site @prannoydidymus ! The structure and API reference are useful, but several examples and formulas need corrections before merging:

1. Fix the custom explainer example (docs/extending.md, lines 32–51). Running it raises AttributeError because ModelAdapter.predict_scalar() does not exist. Use self._predict_scalar(..., target)[0] to obtain each scalar prediction. Also replace instance=x with x=x in _make_explanation() and pass step_size=eps directly instead of nesting it inside metadata.

2. Correct the Borda formula (docs/methods/consensus.md, lines 30–35). The implementation uses (n_features - rank + 1) / n_features, averages these scores using normalized method weights, and applies the mean direction. The documented formula instead gives larger scores to less important features and introduces a normalization absent from the implementation.

3. Correct the surrogate description (docs/methods/surrogate.md, lines 13–38). Default perturbations are centered on the background mean; centering on the instance requires sample_around_instance=True. The kernel is exp(-D² / (2 * kernel_width²)). Continuous-feature contributions use standardized values, coef_i * (x_i - mean_i) / std_i, with categorical features handled through indicator encoding.

4. Fix permutation metrics and uncertainty terminology (docs/methods/permutation.md, lines 24–39). Both metric="mse" and metric="roc_auc" raise ValueError. Document the supported names, including neg_mse and neg_mae; ROC AUC requires a custom callable. Also, importances_std is the population standard deviation across repeats (ddof=0), not a standard error or sample standard deviation.

Please also resolve the README conflict with current main, preserving the notebook link introduced by #23, and add executable smoke checks for the documentation examples.

The documentation builds pass, but these issues affect users following the guides, so I’m requesting changes.

[adaumsilva]

Thanks for adding the documentation site! The structure and API reference are useful, but several examples and formulas need corrections before merging:

1. Fix the custom explainer example (docs/extending.md, lines 32–51). Running it raises AttributeError because ModelAdapter.predict_scalar() does not exist. Use self._predict_scalar(..., target)[0] to obtain each scalar prediction. Also replace instance=x with x=x in _make_explanation() and pass step_size=eps directly instead of nesting it inside metadata.

2. Correct the Borda formula (docs/methods/consensus.md, lines 30–35). The implementation uses (n_features - rank + 1) / n_features, averages these scores using normalized method weights, and applies the mean direction. The documented formula instead gives larger scores to less important features and introduces a normalization absent from the implementation.

3. Correct the surrogate description (docs/methods/surrogate.md, lines 13–38). Default perturbations are centered on the background mean; centering on the instance requires sample_around_instance=True. The kernel is exp(-D² / (2 * kernel_width²)). Continuous-feature contributions use standardized values, coef_i * (x_i - mean_i) / std_i, with categorical features handled through indicator encoding.

4. Fix permutation metrics and uncertainty terminology (docs/methods/permutation.md, lines 24–39). Both metric="mse" and metric="roc_auc" raise ValueError. Document the supported names, including neg_mse and neg_mae; ROC AUC requires a custom callable. Also, importances_std is the population standard deviation across repeats (ddof=0), not a standard error or sample standard deviation.

Please also resolve the README conflict with current main, preserving the notebook link introduced by #23, and add executable smoke checks for the documentation examples.

The documentation builds pass, but these issues affect users following the guides, so I’m requesting changes.

[prannoydidymus]

Please review if the work done is enough @adaumsilva

[adaumsilva]

Thanks for contributing @prannoydidymus PR Merged! Good job! Remember to star the repo if you didn't yet.

[prannoydidymus]

Thank you so much, @adaumsilva! It was a pleasure contributing to your repository. I really appreciate the opportunity and enjoyed working on it.