Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,32 @@ jobs:
if: ${{ matrix.coverage }}
run: uv build

docs:
name: Docs
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
with:
fetch-depth: 0 # required for setuptools-scm to read git tags
persist-credentials: false
# Same Python as Read the Docs (.readthedocs.yml)
- name: Set up uv and Python 3.11
uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
python-version: "3.11"
activate-environment: true
enable-cache: true
cache-dependency-glob: uv.lock
# Same install as Read the Docs. Non-editable, so the docs import the built package, not the checkout.
- name: Install doc dependencies
run: uv sync --locked --no-editable --no-default-groups --group doc --extra report
- name: Prepare tutorials and demo report
run: python scripts/prepare_docs.py
# Any warning fails the build (`--keep-going` still reports them all)
- name: Build docs
run: sphinx-build -W --keep-going -b html docs docs/_build/html

lowest_deps:
name: Lowest Dependencies
needs: code_quality
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,9 @@ instance/

# Sphinx documentation
docs/_build/
# Generated by scripts/prepare_docs.py
docs/_generated/
docs/tutorials/

# PyBuilder
target/
Expand Down
35 changes: 15 additions & 20 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,30 +8,25 @@ version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py

# Build documentation with MkDocs
#mkdocs:
# configuration: mkdocs.yml

# Optionally build your docs in additional formats such as PDF
# formats:
# - pdf
fail_on_warning: true

build:
os: ubuntu-22.04
os: ubuntu-24.04
tools:
python: "3.11"
jobs:
# setuptools-scm derives the version from the git tags
post_checkout:
- git fetch --unshallow --tags || true
# `doc` is a dependency group, which `python.install` below cannot install
post_install:
- python -m pip install --upgrade "pip>=25.1"
- python -m pip install --group doc

# Optionally set the version of Python and requirements required to build your docs
python:
install:
- method: pip
path: .
extra_requirements: [report]
pre_create_environment:
- asdf plugin add uv
- asdf install uv latest
- asdf global uv latest
create_environment:
- uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
# Same locked versions as CI. Non-editable, so the docs import the built package, not the checkout.
install:
- UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --locked --no-editable --no-default-groups --group doc --extra report
# Tutorial notebooks and demo report (published as report.html, linked from the README)
pre_build:
- '"${READTHEDOCS_VIRTUALENV_PATH}/bin/python" scripts/prepare_docs.py'
28 changes: 25 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,15 +200,37 @@ If your change affects how users work with Shapash, update the documentation alo
and re-run that notebook. With uv, add the Jupyter kernel with `--group notebook` (for example
`uv sync --group notebook`); a plain `uv sync` removes it.

To build the documentation locally (the notebook pages need [pandoc](https://pandoc.org/installing.html)
installed):
To build the documentation locally:

```
uv sync --group doc
make docs
```

This builds the HTML pages in `docs/_build/html/` and opens them in your browser.
This builds the HTML pages in `docs/_build/html/` and opens them in your browser. Without `make`
(on Windows, for example), run the two steps yourself:

```
python scripts/prepare_docs.py
sphinx-build -W --keep-going docs docs/_build/html
```

`scripts/prepare_docs.py` copies the tutorial notebooks into `docs/tutorials/`, generates the demo
report and lists the released versions for the version switcher; add `--skip-report` to reuse the report
from a previous run.

The version switcher stays empty when the pages are opened as files. To check it, serve the build with
`python -m http.server -d docs/_build/html` and open http://localhost:8000.

The build downloads the Python, numpy, pandas, scikit-learn and plotly inventories to link their types.
Without network access, for example behind a proxy, set the `SHAPASH_DOCS_OFFLINE` environment variable to `1`
(`SHAPASH_DOCS_OFFLINE=1 make docs`, or `set SHAPASH_DOCS_OFFLINE=1` first on Windows) to skip them.

Like CI, which builds the documentation on every pull request, these commands fail on any Sphinx
warning (`--keep-going` still lists them all).

To check the external links, for example before a release, run `make -C docs linkcheck` after a
documentation build.

## Change dependencies

Expand Down
3 changes: 2 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,9 @@ coverage-report: ## run tests with coverage and generate xml report
pytest --cov=shapash --cov-branch --cov-report=xml

docs: ## generate Sphinx HTML documentation, including API docs
python scripts/prepare_docs.py
$(MAKE) -C docs clean
$(MAKE) -C docs html
$(MAKE) -C docs html SPHINXOPTS="-W --keep-going"
python -m webbrowser "file://$(CURDIR)/docs/_build/html/index.html"

dist: clean ## builds source and wheel package
Expand Down
15 changes: 15 additions & 0 deletions docs/_static/css/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
/* Let wide code blocks in docstring parameter lists scroll instead of widening the whole list */
dl.field-list > dd {
min-width: 0;
}

/* Center the links next to the logo in the company table of the home page */
table.company-table td {
vertical-align: middle;
}

/* The version switcher of the header replaces the Read the Docs flyout, which old releases built with
sphinx_material still show */
readthedocs-flyout {
display: none !important;
}
Binary file added docs/_static/shapash-resize-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
71 changes: 0 additions & 71 deletions docs/_templates/sidebar.html

This file was deleted.

72 changes: 62 additions & 10 deletions docs/autodocs/index.rst
Original file line number Diff line number Diff line change
@@ -1,17 +1,69 @@
.. index:

Documentation
API reference
=============

.. toctree::
:maxdepth: 2
The public API of Shapash. Each entry links to its full documentation.

Tabular data
------------

.. currentmodule:: shapash

.. autosummary::

explainer.smart_explainer.SmartExplainer
explainer.smart_plotter.SmartPlotter
explainer.consistency.Consistency
explainer.smart_predictor.SmartPredictor
utils.load_smartpredictor.load_smartpredictor
data.data_loader.data_loading

Report and standalone plots
---------------------------

shapash.explainer.rst
shapash.predictor.rst
shapash.load_smartpredictor.rst
shapash.data.rst
.. autosummary::

report.ReportTemplate
report.export_report_yml
report.blocks.ReportBlockMixin
report.blocks.block
plots.plot_univariate.plot_distribution
plots.plot_correlations.plot_correlations
plots.plot_evaluation_metrics.plot_confusion_matrix
plots.plot_feature_importance.plot_feature_importance

Backends
--------

.. autosummary::

backend.BaseBackend
backend.ShapBackend
backend.LimeBackend

Text data (NLP)
---------------

.. autosummary::

explainer.nlp_explainer.NlpExplainer
explainer.nlp_explanation.NlpExplanation
explainer.nlp_plotter.NlpPlotter
webapp.nlp_app.NlpWebApp
model.HFClassifierModel
model.HFPipelineModel
backend.NlpShapBackend
backend.NlpLimeBackend
backend.NlpCaptumLigBackend

.. toctree::
:maxdepth: 2
:hidden:

License is Apache Software License 2.0
shapash.explainer
shapash.predictor
shapash.load_smartpredictor
shapash.data
shapash.report
shapash.plots
shapash.backend
shapash.nlp
12 changes: 12 additions & 0 deletions docs/autodocs/shapash.backend.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
Backends
========

A backend computes the contributions that Shapash displays. Pass one to ``SmartExplainer`` with the
``backend`` argument, as a name (``"shap"``, ``"lime"``) or an instance. Subclass ``BaseBackend`` to
write your own.

.. autoclass:: shapash.backend.BaseBackend

.. autoclass:: shapash.backend.ShapBackend

.. autoclass:: shapash.backend.LimeBackend
10 changes: 2 additions & 8 deletions docs/autodocs/shapash.data.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,6 @@ Data Loader
To test **Shapash** library, it provides a data_loader function which returns clearly
labeled datasets.
These datasets allow any new user to easily test the shapash library
on a classification or regression problem
on a classification or regression problem.




.. automodule:: shapash.data.data_loader
:members:
:undoc-members:
:show-inheritance:
.. autofunction:: shapash.data.data_loader.data_loading
14 changes: 5 additions & 9 deletions docs/autodocs/shapash.explainer.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,16 @@ SmartExplainer declaration and data preparation
-----------------------------------------------

.. autoclass:: shapash.explainer.smart_explainer.SmartExplainer
:members: compile, add, save, load, filter, to_pandas, run_app, generate_report
:undoc-members:
:show-inheritance:
:exclude-members: check_attributes, check_x_y_attributes


The Plot Methods
----------------

The plots are methods of the ``plot`` attribute of a compiled ``SmartExplainer``, for example
``xpl.plot.features_importance()``.

.. autoclass:: shapash.explainer.smart_plotter.SmartPlotter
:members: features_importance, contribution_plot, local_plot, compare_plot, top_interactions_plot, local_neighbors_plot, stability_plot, compacity_plot
:undoc-members:
:show-inheritance:
:exclude-members: define_style_attributes

.. autoclass:: shapash.explainer.consistency.Consistency
:members: consistency_plot
:undoc-members:
:show-inheritance:
5 changes: 1 addition & 4 deletions docs/autodocs/shapash.load_smartpredictor.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,4 @@ SmartPredictor Loader Function

This function allows users to load SmartPredictor object saved into a pickle.

.. automodule:: shapash.utils.load_smartpredictor
:members:
:undoc-members:
:show-inheritance:
.. autofunction:: shapash.utils.load_smartpredictor.load_smartpredictor
Loading
Loading