Merge pull request #44 from simonprovost/feature/pypi-publishment

feat(ci): add publish pypi job

.github/workflows/documentation-deploy.yml

@@ -3,6 +3,8 @@ on:
   push:
     branches:
       - main
+    paths:
+      - 'docs/**'
 permissions:
   contents: write
 jobs:

.github/workflows/publish-pypi.yml

@@ -0,0 +1,75 @@
+name: publish-pypi
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  check_build_trigger:
+    name: Check build trigger
+    runs-on: ubuntu-latest
+    outputs:
+      build: ${{ steps.check_build_trigger.outputs.build }}
+
+    steps:
+      - name: Checkout scikit-longitudinal
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - id: check_build_trigger
+        name: Check build trigger
+        run: bash build_tools/github/check_build_trigger.sh
+
+  unit_testing:
+    runs-on: ${{ matrix.os }}
+    needs: check_build_trigger
+    if: needs.check_build_trigger.outputs.build
+    strategy:
+      matrix:
+        python-version: [ 3.9 ]
+        os: [ ubuntu-latest ]
+
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+
+      - name: Checkout this repository
+        uses: actions/checkout@v2
+
+      - uses: pdm-project/setup-pdm@main
+        name: Setup PDM
+        with:
+          python-version: 3.9
+          architecture: x64
+          prerelease: false
+          enable-pep582: true
+
+      - name: Install dependencies from pdm.lock
+        run: |
+          pdm install
+
+      - name: Run tests
+        run: pdm run tests
+
+  pypi-publish:
+    name: ☁️ upload release to PyPI
+    runs-on: ubuntu-latest
+    needs: [check_build_trigger, unit_testing]
+    if: |
+      always() &&
+      needs.check_build_trigger.outputs.build &&
+      needs.unit_testing.result == 'success'
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: pdm-project/setup-pdm@v3
+
+      - name: Publish package distributions to PyPI
+        run: pdm publish

.github/workflows/.unit-test-ci.yml → .github/workflows/unit-test-ci.yml

@@ -5,13 +5,32 @@ on:
     branches:
       - main
 
+
 jobs:
+  check_tests_trigger:
+    name: Check Tests trigger
+    runs-on: ubuntu-latest
+    outputs:
+      tests: ${{ steps.check_tests_trigger.outputs.tests }}
+
+    steps:
+      - name: Checkout scikit-longitudinal
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - id: check_tests_trigger
+        name: Check tests trigger
+        run: bash build_tools/github/check_tests_trigger.sh
+
   Testing:
     runs-on: ${{ matrix.os }}
+    needs: check_tests_trigger
+    if: needs.check_tests_trigger.outputs.tests
     strategy:
       matrix:
-        python-version: [ 3.9 ]
-        os: [ ubuntu-latest ]
+        python-version: [3.9]
+        os: [ubuntu-latest]
 
     steps:
       - name: Set up Python
@@ -35,4 +54,4 @@ jobs:
           pdm install
 
       - name: Run tests
-        run: pdm run tests
+        run: pdm run tests

MANIFEST.in

@@ -0,0 +1,41 @@
+include *.rst
+include LICENSE
+include README.md
+include pyproject.toml
+include setup.py
+include .coveragerc
+include .flake8
+include .dockerignore
+include .gitignore
+include .nojekyll
+include .pre-commit-config.yaml
+include CHANGELOG.MD
+include CITATION.cff
+include dockerfile
+include logo.png
+include mkdocs.yml
+include mkgendocs.yml
+include pdm.lock
+include pylintrc
+include pytest.ini
+
+recursive-include scikit_longitudinal *.py *.c *.cpp *.h *.pyx *.pxd *.pxi *.tp
+recursive-include docs *
+
+# Exclude unnecessary directories and files
+recursive-exlude scikit_longitudinal/tests *
+recursive-exclude .cache *
+recursive-exclude .github *
+recursive-exclude __pypackages__ *
+recursive-exclude dist *
+recursive-exclude .pdm-build *
+recursive-exclude .pytest_cache *
+recursive-exclude .run *
+recursive-exclude .venv *
+recursive-exclude htmlcov *
+recursive-exclude .coverage *
+recursive-exclude .coverage.* *
+recursive-exclude workflows *
+exclude .unit-test-ci.yml
+exclude documentation-deploy.yml
+exclude publish-pypi.yml

README.md

@@ -3,7 +3,7 @@
    <p align="center">
    <h1 align="center">
       <br>
-      <a href="./logo.png"><img src="./logo.png" alt="Scikit-longitudinal" width="200"></a>
+      <a href="https://raw.githubusercontent.com/simonprovost/scikit-longitudinal/main/logo.png?token=GHSAT0AAAAAACIVGTU4VMW5XBIL6ITAYXJSZUFEX2Q"><img src="https://raw.githubusercontent.com/simonprovost/scikit-longitudinal/main/logo.png?token=GHSAT0AAAAAACIVGTU4VMW5XBIL6ITAYXJSZUFEX2Q" alt="Scikit-longitudinal" width="200"></a>
       <br>
       Scikit-longitudinal
       <br>
@@ -97,7 +97,7 @@
 
 ## <a id="about-the-project"></a>💡 About The Project
 
-`Scikit-longitudinal` is a machine learning library designed to analyse
+`Scikit-longitudinal` (Sklong) is a machine learning library designed to analyse
 longitudinal data (Classification tasks focussed as of today). It offers tools and models for processing, analysing,
 and predicting longitudinal data, with a user-friendly interface that
 integrates with the `Scikit-learn` ecosystem.
@@ -106,10 +106,69 @@ Please for further information, visit the [official documentation](https://simon
 
 ## <a id="installation"></a>🛠️ Installation
 
-**ON-HOLD until the first public release**
+To install `Sklong`, take these two easy steps:
 
-Note that for developers, you should follow up onto the `Contributing` tab
-of the [official documentation](https://simonprovost.github.io/scikit-longitudinal/).
+1. ✅ **Install the latest version of `Sklong`**:
+
+```shell
+pip install Scikit-longitudinal
+```
+You could also install different versions of the library by specifying the version number, 
+e.g. `pip install Scikit-longitudinal==0.0.1`. 
+Refer to [Release Notes](https://github.com/simonprovost/scikit-longitudinal/releases)
+
+2. 📦 **[MANDATORY] Update the required dependencies (Why? See [here](https://github.com/pdm-project/pdm/issues/1316#issuecomment-2106457708))**
+
+`Scikit-longitudinal` incorporates a modified version of `Scikit-Learn` called `Scikit-Lexicographical-Trees`, 
+which can be found at [this Pypi link](https://pypi.org/project/scikit-lexicographical-trees/).
+
+This revised version guarantees compatibility with the unique features of `Scikit-longitudinal`. 
+Nevertheless, conflicts may occur with other dependencies in `Scikit-longitudinal` that also require `Scikit-Learn`. 
+Follow these steps to prevent any issues when running your project.
+
+<details>
+<summary><strong>🫵 Simple Setup: Command Line Installation</strong></summary>
+
+Say you want to try `Sklong` in a very simple environment. Such as without a proper `project.toml` file (`Poetry`, `PDM`, etc).
+Run the following command:
+
+```shell
+pip uninstall scikit-learn && pip install scikit-lexico-trees
+```
+
+*Note: Although the main installation command install both, yet it’s advisable to verify the correct versions used is 
+`Scikit-Lexicographical-trees` to prevent conflicts.*
+</details>
+
+<details>
+<summary><strong>🫵 Project Setup: Using `PDM` (or any other such as `Poetry`, etc.)</strong></summary>
+
+Imagine you have a project being managed by `PDM`, or any other package manager. The example below demonstrates `PDM`. 
+Nevertheless, the process is similar for `Poetry` and others. Consult their documentation for instructions on excluding a 
+package.
+
+Therefore, to prevent dependency conflicts, you can exclude `Scikit-Learn` by adding the provided configuration 
+to your `pyproject.toml` file.
+
+```toml
+[tool.pdm.resolution]
+excludes = ["scikit-learn"]
+```
+
+*This exclusion ensures Scikit-Lexicographical-Trees (used as `Scikit-learn`) is used seamlessly within your project.*
+</details>
+
+### 💻 Developer Notes
+
+For developers looking to contribute, please refer to the `Contributing` section of the [official documentation](https://simonprovost.github.io/scikit-longitudinal/).
+
+## <a id="Supported-Operating-Systems"></a>🛠️ Supported Operating Systems
+
+`Scikit-longitudinal` is compatible with the following operating systems:
+
+- MacOS  
+- Linux 🐧
+- Windows via Docker only (Docker uses Linux containers) 🪟 (To try without but we haven't tested it)
 
 ## <a id="how-to-use"></a></a>🚀 Getting Started
 
@@ -145,10 +204,8 @@ y_pred = model.predict(dataset.X_test)
 
 ## <a id="citation"></a>📝 How to Cite?
 
-Paper's citation information will be added here once published. Currently, it has been submitted to a conference. In the
-meantime,
-for the repository, utilise the button top right corner of the repository "How to cite?".
-Or open the following citation file: [CITATION.cff](./CITATION.cff).
+Paper has been submitted to a conference. In the meantime, for the repository, utilise the button top right corner of the
+repository "How to cite?", or open the following citation file: [CITATION.cff](./CITATION.cff).
 
 ## <a id="license"></a>🔐 License
 

build_tools/github/check_build_trigger.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+set -e
+set -x
+
+COMMIT_MSG=$(git log --no-merges -1 --oneline)
+
+# The commit marker "[cd build]" or "[cd build gh]" will trigger the build when required
+if [[ "$GITHUB_EVENT_NAME" == schedule ||
+      "$COMMIT_MSG" =~ \[cd\ build\] ||
+      "$COMMIT_MSG" =~ \[cd\ build\ gh\] ]]; then
+    echo "build=true" >> $GITHUB_OUTPUT
+fi

build_tools/github/check_tests_trigger.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -e
+set -x
+
+COMMIT_MSG=$(git log --no-merges -1 --oneline)
+
+# The commit marker "[cd build]" or "[cd build gh]" will trigger the build when required
+if [[ "$COMMIT_MSG" =~ \[cd\ tests\] ]]; then
+    echo "tests=true" >> $GITHUB_OUTPUT
+fi

docs/contribution.md

@@ -6,6 +6,12 @@ hide:
 # 🤝 Contributing to Scikit-longitudinal
 # 🤝 Contributing to Scikit-longitudinal
 
+## Table of Contents
+2. [📋 Contributing Guidelines](#contribution-guidelines)
+3. [💻 Installation for Developers](#installation-for-developers)
+
+# 📋 Contribution Guidelines
+
 We welcome contributions from the community and are pleased to have them. Please follow this guide when logging issues or making code changes.
 For the developer installation, please scroll down to the bottom of the page.
 
@@ -60,7 +66,8 @@ Please follow the instructions below for setting up your development environment
 
 ### Step by Step Installation Guide
 
-!!! warning "Fully-working environment setup is not guaranteed on Windows. We recommend using a Unix-based system for development. Such as MacOS or Linux. On Windows, Docker is recommended having been tested on Windows 10 & 11."
+!!! warning "Fully-working environment setup is not guaranteed on Windows. We recommend using a Unix-based system for
+development. Such as MacOS or Linux. On Windows, Docker is recommended having been tested on Windows 10 & 11."
 
 To manually configure your environment, please adhere to the following procedure meticulously:
 
@@ -75,9 +82,10 @@ To manually configure your environment, please adhere to the following procedure
       ```bash
       pdm use 3.9
       ```
+      *Here if you have more than one python version installed, you can select the desired version.*
 
 3. **Project Setup:**
-    - Execute the setup script. This step may prompt you to export certain variables or configure compilers like GCC or Clang. Please comply with the on-screen instructions:
+    - Execute the setup script.
       ```bash
       pdm run setup_sklong
       ```
@@ -93,12 +101,14 @@ To manually configure your environment, please adhere to the following procedure
       ```bash
       conda init bash
       ```
+      *It can appears capricious, if it does not work, you can try to go ahead anyway.*
 
 6. **Shell Configuration:**
     - Source your shell configuration file to apply the changes. Again, replace `.bashrc` with the appropriate file name corresponding to your shell:
       ```bash
       source ~/.bashrc # Replace with ~/.zshrc or ~/.config/fish/config.fish accordingly
       ```
+      *It can appears capricious, if it does not work, you can try to go ahead anyway.*
 
 7. **Activating Virtual Environment:**
     - Activate the virtual environment with the following command:
@@ -111,6 +121,28 @@ To manually configure your environment, please adhere to the following procedure
       ```bash
       pdm run install_project
       ```
+    !!! note "Install Prod only"
+          If you want to install only the production dependencies, you can run:
+          ```bash
+          pdm run install_prod
+          ```
+    !!! note "Install Dev only"
+          If you want to install only the development dependencies, you can run:
+          ```bash
+          pdm run install_dev
+          ```
+   *See further information in the `pyproject.toml` file.*
+
+9. **Running Tests:**
+    - To run the tests, execute the following command:
+      ```bash
+      pdm run tests
+      ```
+    !!! warning "You need to have the dev dependencies installed to run the tests."
+          If you want to install only the development dependencies, you can run:
+          ```bash
+          pdm run install_dev
+          ```
 
 ### ❌ Troubleshooting Errors
 
@@ -135,7 +167,7 @@ If you encounter any errors during the setup process and are unsure how to resol
 
 4. **Remove PDM Virtual Environment**:
    ```bash
-   pdm venv remove_env
+   pdm run remove_env
    ``` 
 
 After following these steps, try to reinstall the project dependencies. If the issue persists,