Skip to content
Merged
Show file tree
Hide file tree
Changes from 10 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'
24 changes: 21 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,15 +199,33 @@ If your change affects how users work with Shapash, update the documentation alo
- The tutorial notebooks are in `tutorial/`. If you change a feature a tutorial demonstrates, update
and re-run that notebook.

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/` and generates the demo
report; add `--skip-report` to reuse the report from a previous run.

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
9 changes: 9 additions & 0 deletions docs/_static/css/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
/* 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;
}
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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the purpose of this file was to change version of shapash documentation, is there a new way of doing it with the last version of sphynx ?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. That template only worked with sphinx_material: it replaced the theme's whole sidebar and used its CSS classes and templates. Since we switched to a new theme, it went away.

Version switching should still works through the Read the Docs switch dropdown menu. I could not check it yet since it must be first merged into develop. It's enabled on the project and is added to every build whatever the theme, so the new docs keep it.

If we want a selector back in the page itself, the simplest way is to reuse the old script as a pydata-sphinx-theme header dropdown. It would read the same Read the Docs version data, so there's nothing to maintain. pydata's built-in switcher also works, but it needs a switcher.json updated at each release. I'd add the dropdown in a follow-up once a second version uses the new theme, or in this PR if you'd rather have it now.

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