Skip to content

Commit cb458d2

Browse files
ElouenGinatElouenGinat
authored
Merge pull request #7 from KhiopsML/add-sphinx-doc
Add sphinx doc
2 parents 7ddc057 + 4865993 commit cb458d2

13 files changed

Lines changed: 344 additions & 3 deletions

File tree

‎.github/workflows/docs.yaml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
name: Docs
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
deploy-gh-pages:
7+
description: Deploy to GH Pages
8+
required: true
9+
type: boolean
10+
default: false
11+
pull_request:
12+
paths:
13+
- docs/**.rst
14+
- docs/conf.py
15+
- docs/make.bat
16+
- docs/Makefile
17+
- docs/requirements.txt
18+
- docs/_static/**.css
19+
- src/khisto/**.py
20+
- .github/workflows/docs.yml
21+
push:
22+
tags: ['*']
23+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
24+
permissions:
25+
contents: read
26+
id-token: write
27+
packages: read
28+
pages: write
29+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest
30+
# queued. However, do NOT cancel in-progress runs as we want to allow these production deployments
31+
# to complete.
32+
concurrency:
33+
group: pages
34+
cancel-in-progress: false
35+
jobs:
36+
build:
37+
runs-on: ubuntu-22.04
38+
steps:
39+
- name: Checkout khisto-python
40+
uses: actions/checkout@v4
41+
- name: Set up Python
42+
uses: actions/setup-python@v5
43+
- name: Set up UV
44+
uses: astral-sh/setup-uv@v6
45+
with:
46+
enable-cache: true
47+
- name: Install doc build requirements
48+
run: |
49+
uv venv .build-env
50+
uv pip install --python .build-env -r docs/requirements.txt
51+
- name: Build Sphinx Documentation
52+
run: |
53+
. .build-env/bin/activate
54+
uv run --active --directory docs make html
55+
deactivate
56+
- name: Upload the docs as an artifact
57+
uses: actions/upload-artifact@v4
58+
with:
59+
name: khisto-python-docs
60+
path: ./docs/_build/html/
61+
# Publish to GH pages on Git tag and manually
62+
publish:
63+
if: github.ref_type == 'tag' && github.event_name == 'workflow_dispatch' && inputs.deploy-gh-pages == true
64+
needs: build
65+
runs-on: ubuntu-22.04
66+
permissions:
67+
contents: write
68+
steps:
69+
- name: Download the docs artifact
70+
uses: actions/download-artifact@v4
71+
with:
72+
name: khisto-python-docs
73+
path: ./docs/_build/html
74+
- name: Deploy web site
75+
run: |
76+
uv venv .publish-env
77+
78+
# Install tool for pushing to GH pages
79+
uv pip install --python .publish-env ghp-import
80+
81+
# Push built site directory contents to GH pages
82+
. .publish-env/bin/activate
83+
uv run ghp-import -m "Deployed ${GITHUB_SHA:0:7}" --push --force --no-jekyll ./docs/_build/html/
84+
deactivate

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/_static/css/custom.css‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
/* Custom header sizes */
2+
h1 {
3+
font-size: 1.85em;
4+
}
5+
6+
h2 {
7+
font-size: 1.55em;
8+
}
9+
10+
h3 {
11+
font-size: 1.30em;
12+
}
13+
14+
h4 {
15+
font-size: 1.10em;
16+
}
17+
18+
h5 {
19+
font-size: 0.90em;
20+
}
21+
22+
img.sidebar-logo {
23+
width: 40px;
24+
}

‎docs/array/histogram/index.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
======================
2+
khisto.array.histogram
3+
======================
4+
5+
.. automodule:: khisto.array.histogram
6+
7+
Main Modules
8+
============
9+
.. autosummary::
10+
:toctree: generated
11+
:recursive:
12+
:nosignatures:
13+
14+
api

‎docs/conf.py‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
import os
9+
import sys
10+
from pathlib import Path
11+
12+
sys.path.append("..")
13+
sys.path.append(os.path.join("..", "src"))
14+
15+
project = 'khisto-python'
16+
copyright = '2026, The Khiops Team'
17+
author = 'The Khiops Team'
18+
release = "0.1.0" # TODO: use pyproject metadata here
19+
20+
# -- General configuration ---------------------------------------------------
21+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
22+
# Do not be strict about any broken references, because of Sphinx limitations in
23+
# getting the Numpy scalar type references:
24+
# see https://github.com/sphinx-doc/sphinx/issues/10974
25+
nitpicky = False
26+
27+
# To avoid using qualifiers like :class: to reference objects within the same context
28+
default_role = "obj"
29+
30+
extensions = [
31+
"sphinx.ext.autodoc",
32+
"sphinx.ext.autosummary",
33+
"sphinx.ext.intersphinx",
34+
"numpydoc",
35+
"sphinx_copybutton",
36+
]
37+
38+
## Numpydoc extension config
39+
numpydoc_show_class_members = False
40+
41+
## Autodoc extension config
42+
autodoc_default_options = {
43+
"members": True,
44+
"inherited-members": False,
45+
"private-members": False,
46+
"show-inheritance": True,
47+
"special-members": False,
48+
}
49+
50+
## Intersphinx extension config
51+
intersphinx_mapping = {
52+
"python": ("https://docs.python.org/3", None),
53+
"numpy": ("https://numpy.org/doc/stable", None),
54+
"matplotlib": ("https://matplotlib.org/stable", None),
55+
}
56+
57+
templates_path = ['_templates']
58+
exclude_patterns = ['_templates', '_build', 'Thumbs.db', '.DS_Store']
59+
60+
61+
62+
# -- Options for HTML output -------------------------------------------------
63+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
64+
65+
html_theme = 'furo'
66+
html_theme_options = {
67+
"light_css_variables": {
68+
"color-brand-primary": "#FF7900",
69+
"color-brand-content": "#F16E00",
70+
"color-brand-visited": "#FF7900",
71+
"color-sidebar-background": "#FFFFFF",
72+
"color-highlighted-background": "#FFD200",
73+
"color-admonition-title--note": "#FF7900",
74+
"color-admonition-title-background--note": "#FFF0E2",
75+
"font-stack": "Helvetica Neue, Helvetica, sans-serif",
76+
},
77+
"dark_css_variables": {
78+
"color-brand-primary": "#FF7900",
79+
"color-brand-content": "#F16E00",
80+
"color-brand-visited": "#FF7900",
81+
"color-sidebar-background": "#000000",
82+
"color-highlighted-background": "#FFD200",
83+
"color-admonition-title--note": "#FF7900",
84+
"color-admonition-title-background--note": "#CC6100",
85+
"font-stack": "Helvetica Neue, Helvetica, sans-serif",
86+
},
87+
# Sets the Github Icon (the SVG is embedded, copied from furo's repo)
88+
"footer_icons": [
89+
{
90+
"name": "GitHub",
91+
"url": "https://github.com/khiopsml/khisto-python",
92+
"html": """
93+
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
94+
<path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
95+
</svg>
96+
""",
97+
"class": "",
98+
},
99+
],
100+
}
101+
html_title = f"<h6><center>{project} {release}</center></h6>"
102+
html_static_path = ['_static']
103+
html_css_files = ["css/custom.css"]

‎docs/core/index.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
============
2+
khisto.core
3+
============
4+
5+
.. automodule:: khisto.core
6+
7+
Main Modules
8+
============
9+
.. autosummary::
10+
:toctree: generated
11+
:recursive:
12+
:nosignatures:
13+
14+
cli_adapter

‎docs/index.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. khisto-python documentation master file, created by
2+
sphinx-quickstart on Fri Mar 6 17:40:33 2026.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
khisto-python documentation
7+
===========================
8+
9+
This is the complete API reference for the Khisto Python library.
10+
11+
.. toctree::
12+
:maxdepth: 2
13+
:caption: API Reference
14+
:hidden:
15+
16+
Histograms <array/histogram/index>
17+
Core <core/index>
18+
Matplotlib <matplotlib/index>
19+

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/matplotlib/index.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
=================
2+
khisto.matplotlib
3+
=================
4+
5+
.. automodule:: khisto.matplotlib
6+
7+
Main Modules
8+
============
9+
.. autosummary::
10+
:toctree: generated
11+
:recursive:
12+
:nosignatures:
13+
14+
hist

‎docs/requirements.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
sphinx>=6.1.0
2+
furo>=2022.12.7
3+
ipykernel>=6.9.1
4+
nbconvert==6.4.4
5+
nbformat==5.3.0
6+
numpy>=2.4.3
7+
matplotlib>=3.10.8
8+
numpydoc>=1.5.0
9+
sphinx-copybutton>=0.5.0

0 commit comments

Comments
 (0)