Merge pull request #48 from jurra/docs

Docs test coverage setup with codecov

.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: deploy-documentation
+
+# Only run this when the master branch
+on:
+  push:
+    branches:
+      - master
+      - develop
+      - feature/sphinx
+  # Option to run action manually
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag for manually deploying docs website
+        required: False
+        default: ""
+permissions:
+  contents: write
+
+# This job installs dependencies, builds the documentaiton, and pushes it to `gh-pages`
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.8
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Install dependencies
+        run: |
+          pip install -e .[docs]
+      - name: Build the documentation
+        run: |
+          cd docs
+          make html
+          touch _build/html/.nojekyll
+      - name: Deploy documentation
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/_build/html
+          token: ${{ secrets.GH_PAGES }}

.github/workflows/pip.yml

@@ -7,7 +7,8 @@ on:
   pull_request:
   push:
     branches:
-      - '*'
+      - develop
+      - main
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -36,10 +37,18 @@ jobs:
     - name: Build and install
       run: pip install --verbose .
 
-    - name: Test
+    - name: Test and generate coverage reports
       run: | 
-        pip install pytest
-        pytest
+        pip install pytest pytest-cov
+        pytest -v --cov=pymurtree --cov-report=xml
+        
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v3
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        file: ./coverage.xml
+        # fail_ci_if_error: true  # Optional: Set to true if you want the workflow to fail when Codecov upload fails
+        verbose: true  # Optional: Set to true if you want more detailed output from the Codecov action
 
   build-mingw64:
     runs-on: windows-latest
@@ -54,13 +63,16 @@ jobs:
           mingw-w64-x86_64-gcc
           mingw-w64-x86_64-python-pip
           mingw-w64-x86_64-python-wheel
+          mingw-w64-x86_64-python-pandas
+          git
+          mingw-w64-x86_64-meson
 
     - uses: actions/checkout@v3
 
-    - name: Install pybind11
+    - name: Add requirements
       # This is required because --no-build-isolation disable dependences
       # installation
-      run: pip install pybind11
+      run: python -m pip install gitpython pybind11 meson-python
 
     - name: Build and install
       # --no-build-isolation is required because the vanilla setuptool does not
@@ -71,4 +83,6 @@ jobs:
       run: pip install --no-build-isolation .
 
     - name: Test
-      run: python tests/test.py
+      run: | 
+        pip install pytest
+        pytest

.github/workflows/wheels.yml

@@ -7,7 +7,8 @@ on:
   workflow_dispatch:
   pull_request:
   push:
-    branches: [ '*'  ]
+    branches: 
+      - main
   release:
     types:
       - published

.gitignore

@@ -36,6 +36,10 @@ share/python-wheels/
 *.egg
 MANIFEST
 
+# Docs
+**/_build/
+
+
 # Installer logs
 pip-log.txt
 pip-delete-this-directory.txt
@@ -45,3 +49,4 @@ _no_*
 **/__pycache__/
 *pymurtree_data/
 **/*.cpython*
+*.pyd

README.md

@@ -1,8 +1,16 @@
 # PyMurTree 
-> DISCLAIMER: This codebase is currently in alpha version, meaning that the main branch version is made available for testing mainly by project members. Please note that this codebase is still under development and may contain bugs or errors. Users are advised to exercise caution when using this codebase and to report any issues or feedback to the developers so they can be addressed in future releases.
 
+[![GitHub](https://img.shields.io/github/license/MurTree/pymurtree?)](https://github.com/MurTree/pymurtree/blob/master/LICENSE)
+![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/MurTree/pymurtree/wheels.yml)
+[![codecov](https://codecov.io/gh/MurTree/pymurtree/branch/develop/graph/badge.svg?token=2TKHE7IN49)](https://codecov.io/gh/MurTree/pymurtree)
+![GitHub repo size](https://img.shields.io/github/repo-size/MurTree/pymurtree)
 
-PyMurTree is a Python wrapper for the [MurTree project](https://github.com/DCC/murtree). The MurTree algorithm constructs optimal classification trees that minimize the misclassification score of a given dataset while respecting constraints on depth and number of feature nodes. The sparse objective, which penalizes each node added in the tree, is also supported.
+Warning:
+> This repository is under active development and currently in a pre-alpha state. 
+> The current version only supports Linux.
+
+
+PyMurTree is a Python wrapper for the [MurTree project](https://github.com/MurTree/murtree). The MurTree algorithm constructs optimal classification trees that minimize the misclassification score of a given dataset while respecting constraints on depth and number of feature nodes. The sparse objective, which penalizes each node added in the tree, is also supported.
 
 ---
 ## **Citation**
@@ -58,26 +66,7 @@ ctest
 
 ## Usage
 
-### API
-
-The full [API specification](https://github.com/MurTree/pymurtree/wiki/API-documentation) is available in the repo's Wiki. 
-
-pymurtree is implemented as a thin Python wrapper around the main C++ MurTree application. The main functionality of MurTree is exposed in pymurtree via the OptimalDecisionTreeClassifier class. Utility functions to load training datasets and export the tree in text and dot formats are also included in the python package.
-
-**OptimalDecisionTreeClassifier class**
-- `constructor`: initialize the parameters of the model  
-- `fit`: fit a decision tree classifier to the given training dataset
-- `predict`: predict the labels for a set of features
-- `score`: return the accuracy on the given test data and labels
-- `depth`: return the depth of the tree
-- `num_nodes`: return the number of nodes of the tree
-- `export_text`: export decision tree in text format
-- `export_dot`: export decision tree in DOT format
-
-**Utility functions**
-- `read_from_file`: read features and labels from file into a pandas dataframe
-- `load_data`: read features and labels from file into a numpy array
-
+The full [API specification](https://murtree.github.io/pymurtree/api_reference.html) is available in the repo's documentation. 
 
 ### Example
 

docs/LICENSE

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © `2023` `Yasel Quintero, Jose Urra, Koos Van der Linden, Emir Demirovic`
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

docs/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)

docs/api_reference.rst

@@ -0,0 +1,5 @@
+API reference
+=============
+.. automodule:: pymurtree.OptimalDecisionTreeClassifier
+    :members:
+    :exclude-members: standardize_to_dtype_int32

docs/conf.py

@@ -0,0 +1,51 @@
+# 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
+
+import os
+import sys
+import shutil
+
+sys.path.insert(0, os.path.abspath('../src/pymurtree'))
+
+shutil.copyfile('../README.md', './readme.md')
+
+project = 'PyMurTree'
+copyright = '2023, Yasel Quintero, Jose Urra, Emir Demirovic, Koos van der Linden'
+author = 'Yasel Quintero, Jose Urra, Emir Demirovic, Koos van der Linden'
+release = '0.0.1'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.coverage',
+    'sphinx.ext.githubpages',
+    'myst_parser',
+    'sphinx_rtd_theme'
+]
+
+source_suffix = ['.rst', '.md']
+
+# Specify autodoc settings
+napoleon_numpy_docstring = True
+napoleon_use_param = False
+
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,29 @@
+.. PyMurTree documentation master file, created by
+   sphinx-quickstart on Mon Sep 25 10:40:56 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to PyMurTree's documentation!
+=====================================
+
+.. toctree::
+   :maxdepth: 3
+   :caption: PyMurTree
+
+   readme.md
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: For developers
+
+   api_reference
+   lifecycle.md
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/lifecycle.md

@@ -0,0 +1,24 @@
+# Lifecycle & automation
+All the CI automation and lifecycle management is done through GitHub Actions. 
+There are different rules for different workflows.
+
+## Development and branching
+Even though we are not strictly using [git-flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow#:~:text=Gitflow%20is%20an%20alternative%20Git,lived%20branches%20and%20larger%20commits.), we are following a similar branching strategy.
+- All features are developed in feature branches. `git checkout -b feature/my_feature`
+- All features are merged into the `develop` branch. `git checkout develop && git merge feature/my_feature`
+- All bugfixes are developed in bugfix branches. `git checkout -b bugfix/my_bugfix`
+
+### Forking and Pull requests
+- Promote forking of the repository for better collaboration. This is a good practice for open source projects. This will allow you also to have control over rights, permissions and actions environments.
+- This also allows you to have a separate repository for a contributors own development and testing. Contributers can then make a PR to the main repository when you are ready.
+- Contributing from forks can only be made through Pull requests, this makes the overall codebase management more transparent.
+- Furthermore there are specific automations like tests that are triggered on pull requests. This is a good way to make sure that the code is tested before merging, and educates contributors in writing tests.
+
+## What is automated?
+- Tests on every pull request to develop and main branches for all platforms (Linux, Windows, MacOS). Worfklow: [`pip.yaml`](../.github/workflows/pip.yml).
+- Automatic build and distribution to pypi on every release. Workflow: [`pypi.yaml`](../.github/workflows/wheels.yml).
+- Automatic documentation generation. Workflow: [`docs.yaml`](../.github/workflows/docs.yaml).
+
+## Releasing
+- Update the version number in `pyproject.toml`. Do the same for the citation file. `CITAION.cff``.
+- Use the release tag in GitHub to create a new release. This will trigger the automatic build and distribution to pypi. This manual step will trigger the workflow: [`pypi.yaml`](../.github/workflows/wheels.yaml).

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd