Enhance documentation for khisto-python library

- Updated the main index.rst to provide a clearer introduction to Khisto, highlighting its adaptive binning capabilities and various entry points for users.
- Added a description in matplotlib/index.rst to explain the use of khisto.matplotlib.hist for adaptive histogramming, emphasizing its convenience compared to traditional plt.hist.

Author: ElouenGinat

docs/api_comparison.rst

@@ -1,7 +1,7 @@
 API Comparison
 ==============
 
-This document compares the Khisto API with NumPy and Matplotlib, highlighting similarities and differences.
+This document compares the current Khisto APIs with NumPy and Matplotlib.
 
 NumPy Comparison
 ----------------
@@ -155,6 +155,9 @@ Signature Comparison
        color=None,
        label=None,
        ax=None,
+       edgecolor=None,
+       linewidth=None,
+       alpha=None,
        **kwargs,
    )
 
@@ -180,12 +183,18 @@ Key Differences
    * - **Cumulative**
      - Supported
      - Supported
+   * - **Reverse cumulative**
+     - Supported with negative ``cumulative``
+     - Supported with negative ``cumulative``
    * - **Stacked**
      - Supported
      - Not supported
    * - **Weights**
      - Supported
      - Not supported
+   * - **Unsupported histogram args**
+     - None
+     - ``bins``, ``stacked``, and ``weights`` raise a ``TypeError``
    * - **Multiple datasets**
      - Supported
      - Sequences are concatenated into one dataset
@@ -228,6 +237,10 @@ Common Parameters (Same Behavior)
    plt.hist(data, density=True, cumulative=True)
    hist(data, density=True, cumulative=True)
 
+  # reverse cumulative view
+  plt.hist(data, cumulative=-1)
+  hist(data, cumulative=-1)
+
    # histogram type
    plt.hist(data, histtype='step')
    hist(data, histtype='step')
@@ -316,6 +329,10 @@ Feature Matrix
      - No
      - Yes
      - Yes
+   * - Reverse cumulative
+     - No
+     - Yes
+     - Yes
    * - Plotting
      - No
      - Yes

docs/array/histogram/index.rst

@@ -2,6 +2,9 @@
 khisto.array.histogram
 ======================
 
+The fastest way to use Khisto: a NumPy-like ``(hist, bin_edges)`` API with
+adaptive bins, optional ``max_bins`` control, and no plotting overhead.
+
 .. automodule:: khisto.array.histogram
 
 Main Modules
@@ -11,4 +14,5 @@ Main Modules
   :recursive:
   :nosignatures:
 
+  histogram
   api

docs/conf.py

@@ -6,16 +6,32 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 import os
+import re
 import sys
 from pathlib import Path
 
-sys.path.append("..")
-sys.path.append(os.path.join("..", "src"))
+DOCS_DIR = Path(__file__).resolve().parent
+ROOT_DIR = DOCS_DIR.parent
+
+sys.path.append(str(ROOT_DIR))
+sys.path.append(str(ROOT_DIR / "src"))
+
+
+def _read_release() -> str:
+    init_file = ROOT_DIR / "src" / "khisto" / "__init__.py"
+    match = re.search(
+        r'^__version__\s*=\s*"(?P<version>[^"]+)"',
+        init_file.read_text(encoding="utf-8"),
+        re.MULTILINE,
+    )
+    if match is None:
+        raise RuntimeError(f"Could not determine khisto version from {init_file}")
+    return match.group("version")
 
 project = 'khisto-python'
 copyright = '2026, The Khiops Team'
 author = 'The Khiops Team'
-release = "0.1.0" # TODO: use pyproject metadata here
+release = _read_release()
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/core/index.rst

@@ -2,6 +2,9 @@
 khisto.core
 ============
 
+Use ``khisto.core`` when you want to go beyond the default answer and inspect
+the full histogram series returned by the Khiops backend.
+
 .. automodule:: khisto.core
 
 Main Modules
@@ -11,4 +14,6 @@ Main Modules
   :recursive:
   :nosignatures:
 
+  compute_histograms
+  HistogramResult
   backend

docs/demo.ipynb

@@ -6,7 +6,18 @@
 khisto-python documentation
 ===========================
 
-This is the complete API reference for the Khisto Python library.
+Khisto helps you build histograms that look right on the first try.
+
+It replaces fixed-width bin guesses with adaptive bins computed by the Khiops
+algorithm, so dense regions stay detailed and sparse regions stay readable.
+
+Pick the entry point that matches your workflow:
+
+- :doc:`demo` for a runnable tour.
+- :doc:`array/histogram/index` for a NumPy-like API with better bins.
+- :doc:`matplotlib/index` for plots that stay familiar but look sharper.
+- :doc:`core/index` for full access to the histogram series.
+- :doc:`api_comparison` for a quick comparison with NumPy and matplotlib.
 
 .. toctree::
    :maxdepth: 2

docs/index.rst

@@ -2,6 +2,9 @@
 khisto.matplotlib
 =================
 
+Use ``khisto.matplotlib.hist`` when you want the convenience of ``plt.hist``
+with bins that adapt to the data instead of flattening it.
+
 .. automodule:: khisto.matplotlib
 
 Main Modules