412 user guide and api documentation

.github/workflows/push_doc.yml

@@ -0,0 +1,54 @@
+name: Build documentation
+
+on:
+  push:
+    branches:
+      - main
+      - test-ci*
+  pull_request:
+    branches:
+      - '**'
+
+permissions:
+  contents: write
+
+jobs:
+  push_doc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - run: pip install .[doc]
+
+      - name: Sphinx build
+        run: sphinx-build doc build
+
+      - name: Save the PR number
+        env:
+          GITHUB_PULL_REQUEST_NUMBER: ${{github.event.number}}
+        run: |
+          echo "Storing PR number ${{github.event.number}} to 'pull_request_number' file"
+          echo ${{github.event.number}} > pull_request_number
+
+      - name: Upload doc preview
+        # The publication of the preview itself happens in pr-doc-preview.yml
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: doc-preview
+          path: |
+            ./build
+            pull_request_number
+
+      - name: Deploy
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build
+          commit_message: "[ci skip] ${{ github.event.head_commit.message }}"

.gitignore

@@ -164,6 +164,10 @@ cython_debug/
 .DS_Store
 *.datamander
 
+# Sphinx documentation
+doc/_build/
+doc/auto_examples/
+
 # Visual studio code
 .vscode
 

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/_static/css/custom.css

@@ -0,0 +1,43 @@
+div.docutils.container.index-features {
+    width: 300px;
+}
+
+div.docutils.container.index-box {
+    background-color: var(--pst-color-white-highlight);
+    border-radius: 10px;
+    color: black;
+    padding: 5px;
+    margin-left: 15px;
+    float: right;
+    width: 400px;
+}
+
+/* Need to be able to have absolute positioning for the div inside */
+.bd-main .bd-content .bd-article-container .bd-article {
+    position: relative;
+}
+
+@media (min-width: 792px) {
+    div.docutils.container.index-features {
+        position: absolute;
+        top: 10px;
+        right: 0px;
+    }
+}
+
+@media (min-width: 1092px) {
+    div.docutils.container.index-box {
+        margin-left: 30px;
+        margin-right: -15px;
+    }
+}
+
+@media (max-width: 892px) {
+    div.docutils.container.index-box {
+        max-width: 500px;
+        width: unset;
+        float: unset;
+        margin-left: auto;
+        margin-right: auto;
+    }
+}

doc/_templates/class.rst

@@ -0,0 +1,19 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}==============
+
+.. rst-class:: side_comment
+
+    Usage examples at the bottom of this page.
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :inherited-members:
+
+   {% block methods %}
+
+   {% endblock %}
+
+.. raw:: html
+
+    <div class="clearer"></div>

doc/_templates/function.rst

@@ -0,0 +1,10 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}====================
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. raw:: html
+
+    <div class="clearer"></div>

doc/api.rst

@@ -0,0 +1,18 @@
+API
+===
+
+This page lists all the public functions and classes of the `skore`
+package:
+
+.. currentmodule:: skore
+
+
+Project
+-------
+
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+    :nosignatures:
+
+    Project

doc/conf.py

@@ -0,0 +1,60 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "skore"
+copyright = "2024, Probabl team"
+author = "Probabl team"
+release = "0.1.1"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx_gallery.gen_gallery",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "numpydoc",
+    "sphinx_design",
+]
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
+
+html_css_files = [
+    "css/custom.css",
+]
+html_js_files = []
+
+# sphinx_gallery options
+sphinx_gallery_conf = {
+    "examples_dirs": "../examples",  # path to example scripts
+    "gallery_dirs": "auto_examples",  # path to gallery generated output
+}
+
+# intersphinx configuration
+intersphinx_mapping = {
+    "sklearn": ("https://scikit-learn.org/stable/", None),
+}
+
+numpydoc_show_class_members = False
+
+html_title = "skore"
+
+html_theme_options = {
+    "announcement": (
+        "https://raw.githubusercontent.com/soda-inria/hazardous/main/doc/announcement.html"
+    ),
+}

doc/generated/skore.Project.rst

@@ -0,0 +1,19 @@
+:mod:`skore`.Project
+===========================
+
+.. rst-class:: side_comment
+
+    Usage examples at the bottom of this page.
+
+.. currentmodule:: skore
+
+.. autoclass:: Project
+   :inherited-members:
+
+
+
+
+
+.. raw:: html
+
+    <div class="clearer"></div>

doc/index.rst

@@ -0,0 +1,59 @@
+.. You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+skore
+=====
+
+Gradient-boosting survival analysis
+-----------------------------------
+
+.. container:: index-features
+
+   * survival and competing risks
+
+   * scikit-learn compatible
+
+   * scalable gradient boosting
+
+A scalable **time-to-event and competing risk prediction model**
+implemented in Python.
+
+.. container:: index-box sd-card
+
+   **Competing risks settings**
+
+   Predicting which event will happen first, and when, from data where some
+   events have not yet been observed:
+
+The model is **a gradient-boosting variant**, that offers prediction for
+survival and competing risks settings, fully compatible with
+`scikit-learn <https://scikit-learn.org>`_. It can be used with
+scikit-learn tools such as pipelines, column transformers,
+cross-validation, hyper-parameter search tools, etc.
+
+.. This package will also offer neural network based estimators by leveraging
+   `PyTorch <https://pytorch.org>`_ and `skorch
+   <https://skorch.readthedocs.io/>`_.
+
+This library puts a focus on predictive accuracy rather than on inference.
+Quantifying the statistical association or causal effect of covariates with/on
+the cumulated event incidence or instantaneous hazard rate is not in the scope
+of this library at this time.
+
+The theory behind the model is described in `this paper
+<https://arxiv.org/abs/2406.14085>`_.
+
+- License: MIT
+- GitHub repository: https://github.com/soda-inria/hazardous
+- Changelog: https://github.com/soda-inria/hazardous/blob/main/CHANGES.rst
+- Status: under development, API is subject to change without notice.
+
+.. currentmodule:: skore
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   api
+   auto_examples/index
+   user_guide

doc/sg_execution_times.rst

@@ -0,0 +1,40 @@
+
+:orphan:
+
+.. _sphx_glr_sg_execution_times:
+
+
+Computation times
+=================
+**00:00.681** total execution time for 2 files **from all galleries**:
+
+.. container::
+
+  .. raw:: html
+
+    <style scoped>
+    <link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/5.3.0/css/bootstrap.min.css" rel="stylesheet" />
+    <link href="https://cdn.datatables.net/1.13.6/css/dataTables.bootstrap5.min.css" rel="stylesheet" />
+    </style>
+    <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
+    <script src="https://cdn.datatables.net/1.13.6/js/jquery.dataTables.min.js"></script>
+    <script src="https://cdn.datatables.net/1.13.6/js/dataTables.bootstrap5.min.js"></script>
+    <script type="text/javascript" class="init">
+    $(document).ready( function () {
+        $('table.sg-datatable').DataTable({order: [[1, 'desc']]});
+    } );
+    </script>
+
+  .. list-table::
+   :header-rows: 1
+   :class: table table-striped sg-datatable
+
+   * - Example
+     - Time
+     - Mem (MB)
+   * - :ref:`sphx_glr_auto_examples_plot_demo.py` (``../examples/plot_demo.py``)
+     - 00:00.652
+     - 0.0
+   * - :ref:`sphx_glr_auto_examples_plot_demo_2.py` (``../examples/plot_demo_2.py``)
+     - 00:00.029
+     - 0.0

doc/user_guide.rst

@@ -0,0 +1,8 @@
+.. _user_guide:
+
+User guide
+==========
+
+.. currentmodule:: skore
+
+*The user guide is incoming.*

examples/README.rst

@@ -0,0 +1,5 @@
+Examples
+========
+
+Below is a gallery of examples on how to use `skore` for predictive
+competitive risk analysis problems.