update README; conftest for rst; workflow build docs; logging

.github/workflows/test.yml

@@ -1,32 +1,53 @@
-name: Unit tests
+name: Unit tests and docs generation
 
 on:
   push:
     branches:
       - "**"
   pull_request:
+    branches:
+      - "**"
     types: [opened, synchronize, reopened, ready_for_review]
   workflow_dispatch:
 
 jobs:
   check:
     if: github.event.pull_request.draft == false
-    runs-on: ${{matrix.os}}
+    runs-on: ubuntu-latest
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ['3.8', '3.9', '3.10', '3.11']
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
     defaults:
       run:
         shell: bash -l {0}
 
     steps:
+      - name: Set OS and Python version
+        id: set-vars
+        run: |
+          if [[ "${GITHUB_REF}" == "refs/heads/main" || "${GITHUB_REF}" == "refs/heads/dev" ]]; then
+            echo "os-matrix=ubuntu-latest,windows-latest" >> $GITHUB_ENV
+            echo "python-matrix=3.8,3.9,3.10,3.11" >> $GITHUB_ENV
+          else
+            echo "os-matrix=ubuntu-latest" >> $GITHUB_ENV
+            echo "python-matrix=3.11" >> $GITHUB_ENV
+          fi
       - name: Checkout
         uses: actions/checkout@v3
       - name: Python
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
+      - name: Cache Poetry
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cache/pypoetry
+            ~/.cache/pip
+          key: ${{ runner.os }}-poetry-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-poetry-${{ matrix.python-version }}-
       - name: Poetry
         uses: snok/install-poetry@v1
         with:
@@ -41,3 +62,42 @@ jobs:
         uses: codecov/codecov-action@v3
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  docs:
+    runs-on: ubuntu-latest
+    needs: check
+    if: github.event_name == 'push' || github.event_name == 'pull_request'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Cache Poetry
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cache/pypoetry
+            ~/.cache/pip
+          key: ${{ runner.os }}-poetry-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-poetry-${{ matrix.python-version }}-
+      - name: Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: 1.8.3
+      - name: Lock
+        run: poetry lock --no-update
+      - name: Install
+        run: poetry install
+      - name: Check Changed Files
+        id: changed-files
+        run: |
+          git fetch origin ${{ github.base_ref }}:${{ github.base_ref }} --depth=1
+          git diff --name-only ${{ github.base_ref }} > changed_files.txt
+      - name: Build Docs
+        if: contains(fromJSON('["docs/", ".rst"]').join(','), fromJSON('["${{ steps.changed-files.outputs.files }}"]').join(','))
+        run: |
+          poetry run sphinx-build -b html docs/ _build/html

README.rst

@@ -70,14 +70,13 @@ With just these few lines of code, you can see how easy it is to
   from qolmat.utils import data
 
   # load and prepare csv data
-
   df_data = data.get_data("Beijing")
   columns = ["TEMP", "PRES", "WSPM"]
   df_data = df_data[columns]
   df_with_nan = data.add_holes(df_data, ratio_masked=0.2, mean_size=120)
 
   # impute and compare
-  imputer_mean = imputers.ImputerMean(groups=("station",))
+  imputer_mean = imputers.ImputerSimple(strategy="mean", groups=("station",))
   imputer_interpol = imputers.ImputerInterpolation(method="linear", groups=("station",))
   imputer_var1 = imputers.ImputerEM(model="VAR", groups=("station",), method="mle", max_iter_em=50, n_iter_ou=15, dt=1e-3, p=1)
   dict_imputers = {
@@ -90,7 +89,7 @@ With just these few lines of code, you can see how easy it is to
         dict_imputers,
         columns,
         generator_holes = generator_holes,
-        metrics = ["mae", "wmape", "KL_columnwise", "ks_test", "energy"],
+        metrics = ["mae", "wmape", "kl_columnwise", "ks_test", "energy"],
     )
   results = comparison.compare(df_with_nan)
   results.style.highlight_min(color="lightsteelblue", axis=1)

docs/Makefile

@@ -37,6 +37,9 @@ clean:
 	-rm -rf examples/tutorials/*
 	-rm -rf generated/*
 
+doctest:
+	$(SPHINXBUILD) -b doctest . _build/doctest
+
 html:
 	# These two lines make the build a bit more lengthy, and the
 	# the embedding of images more robust

docs/conf.py

@@ -159,6 +159,11 @@
     "reference_url": {"qolmat": None},
 }
 
+suppress_warnings = ["autosectionlabel.*"]
+
+# doctest configuration
+doctest_test_doctest_blocks = "default"
+
 html_css_files = [
     "custom.css",
 ]