Merge pull request #334 from dice-group/general_adjustments

Removed conda, updated docs workflow, updated docs

.github/workflows/docs.yml

@@ -1,56 +1,63 @@
-#name: Build docs
-#
-#on:
-#  push:
-#    branches:
-#     - master
-#     - develop
-#  pull_request:
-#
-#jobs:
-#  docs:
-#    runs-on: ubuntu-latest
-#    strategy:
-#      max-parallel: 5
-#
-#    steps:
-#    - uses: actions/checkout@v3
-#    - name: Install tox
-#      id: install-tox
-#      run: |
-#        pip install tox
-#        echo "tox_version=$(pip list | grep tox | tr -d ' ')" >> $GITHUB_OUTPUT
-#    - name: prepare required software
-#      run: |
-#        # epstopdf & dot & noto-fonts
-#        sudo apt update && sudo apt install texlive-font-utils graphviz fonts-noto
-#    - uses: actions/cache@v3
-#      with:
-#        key: ${{ runner.os }}-${{ steps.install-tox.outputs.tox_version }}-docs-${{ hashFiles('environment.yml', 'tox.ini') }}
-#        path: .tox
-#    - name: Build docs with tox
-#      run: |
-#        tox -o -e docs
-#    - name: Build latex docs with tox
-#      run: |
-#        tox -o -e docs -- latex
-#    - name: Compile LaTeX document
-#      uses: docker://texlive/texlive:latest
-#      with:
-#        args: make -C docs/_build/latex
-#    - run: |
-#        cp docs/_build/latex/ontolearn.pdf docs/_build/html/
-#    - name: Deploy to netlify
-#      uses: nwtgck/actions-netlify@v1.2
-#      with:
-#        publish-dir: 'docs/_build/html'
-#        production-branch: develop
-#        github-token: ${{ secrets.GITHUB_TOKEN }}
-#        deploy-message: "Deploy from GitHub Actions ${{ github.sha }}"
-#        alias: ${{ github.head_ref }}
-#        enable-pull-request-comment: false
-#        enable-commit-comment: false
-#      env:
-#        NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
-#        NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
-#      timeout-minutes: 5
+name: Build docs
+
+on:
+  push:
+    branches:
+     - master
+     - develop
+  pull_request:
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ "3.9.18" ]
+      max-parallel: 5
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt   
+
+    - name: Prepare required software
+      run: |
+        # epstopdf & dot & noto-fonts
+        sudo apt update && sudo apt install texlive-font-utils graphviz fonts-noto\
+
+    - name: Build docs
+      run: |
+        sphinx-build -M html docs/ docs/_build/
+
+    - name: Build LaTeX docs
+      run: |
+        sphinx-build -M latex docs/ docs/_build/
+
+    - name: Compile LaTeX document
+      uses: docker://texlive/texlive:latest
+      with:
+        args: make -C docs/_build/latex
+    - run: |
+        cp docs/_build/latex/ontolearn.pdf docs/_build/html/
+
+    - name: Deploy to netlify
+      uses: nwtgck/actions-netlify@v1.2
+      with:
+        publish-dir: 'docs/_build/html'
+        production-branch: develop
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        deploy-message: "Deploy from GitHub Actions ${{ github.sha }}"
+        alias: ${{ github.head_ref }}
+        enable-pull-request-comment: false
+        enable-commit-comment: false
+      env:
+        NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+      timeout-minutes: 5

.github/workflows/test.yml

@@ -15,11 +15,6 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
-      # - name: Set up Conda
-      #   uses: conda-incubator/setup-miniconda@v2
-      #   with:
-      #    environment-file: environment.yml
-        # conda run -n test pytest -p no:warnings -x
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip

README.md

@@ -21,8 +21,8 @@ pip install ontolearn
 or
 ```shell
 git clone https://github.com/dice-group/Ontolearn.git 
-conda create --name onto python=3.9.18 && conda activate onto && pip3 install -e . && python -c "import ontolearn"
-# To download knowledge graphs
+python -m venv venv && source venv/bin/activate # for Windows use: .\venv\Scripts\activate 
+pip install -r requirements.txt
 wget https://files.dice-research.org/projects/Ontolearn/KGs.zip -O ./KGs.zip && unzip KGs.zip
 ```
 
@@ -153,10 +153,11 @@ python -c 'import pandas as pd; print(pd.read_csv("carcinogenesis_results.csv",
 ## Deployment 
 
 ```shell
-pip install gradio
+pip install gradio # (check `pip show gradio` first)
 ```
 
-To deploy **EvoLearner** on the **Family** knowledge graph. Available models to deploy: **EvoLearner**, **NCES**, **CELOE** and **OCEL**.
+Available models to deploy: **EvoLearner**, **NCES**, **CELOE** and **OCEL**.
+To deploy **EvoLearner** on the **Family** knowledge graph:
 ```shell
 python deploy_cl.py --model evolearner --path_knowledge_base KGs/Family/family-benchmark_rich_background.owl
 ```

docs/conf.py

@@ -10,10 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
 
@@ -27,18 +26,25 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinxext_autox',
+    'autoapi.extension',
     'sphinx.ext.githubpages',
-    # 'sphinx.ext.intersphinx',
-    # 'sphinx_automodapi.smart_resolver',
-    # 'sphinx.ext.inheritance_diagram',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinxcontrib.plantuml',
     'myst_parser',
     'sphinx_rtd_theme',
 ]
 
+# autoapi for ontolearn and owlapy. for owlapy we need to refer to its path in GitHub Action environment
+autoapi_dirs = ['../ontolearn', '/opt/hostedtoolcache/Python/3.9.18/x64/lib/python3.9/site-packages/owlapy']
+
+# by default all are included but had to reinitialize this to remove private members from shoing
+autoapi_options = ['members', 'undoc-members', 'show-inheritance', 'show-module-summary', 'special-members',
+                   'imported-members']
+# this is set to false, so we can add it manually in index.rst together with the other .md files of the documentation.
+autoapi_add_toctree_entry = False
+
+
 inheritance_graph_attrs = dict(rankdir="TB")
 
 myst_enable_extensions = [

docs/index.rst

@@ -16,7 +16,8 @@ Ontolearn is an open-source software library for explainable structured machine
    usage/07_reasoning_details
    usage/08_model_adapter
    usage/09_further_resources
-   api
+   autoapi/ontolearn/index
+   autoapi/owlapy/index
 
 
 .. raw:: latex

docs/usage/01_introduction.md

@@ -1,6 +1,6 @@
 # Ontolearn
 
-**Version:** ontolearn 0.6.0
+**Version:** ontolearn 0.6.2
 
 **GitHub repository:** [https://github.com/dice-group/Ontolearn](https://github.com/dice-group/Ontolearn)
 

docs/usage/02_installation.md

@@ -5,19 +5,15 @@ your system. Python comes in various versions and with different,
 sometimes conflicting dependencies. Hence, most guides will recommend
 to set up a "virtual environment" to work in.
 
-One such system for virtual python environments is
-[Anaconda](https://www.anaconda.com/). You can download miniconda from
-<https://docs.conda.io/en/latest/miniconda.html>.
+One such system for virtual python environments is python
+[venv](https://docs.python.org/3/library/venv.html). Since the command comes 
+together with python, you don't need to install any external tool.
 
-We have good experience with it and make use of conda in the
-[Installation from source](#installation-from-source) step.
 
 ## Installation via _pip_
 
 Released versions of Ontolearn can be installed using `pip`, the
-Package Installer for Python. It comes as part of Python. Please
-research externally (or use `conda create` command below) on how to
-create virtual environments for Python programs.
+Package Installer for Python. `pip` comes as part of Python.
 
 ```shell
 pip install ontolearn
@@ -30,39 +26,36 @@ and all its dependencies from <https://pypi.org/project/ontolearn/>.
 
 To download the Ontolearn source code, you will also need to have a
 copy of the [Git](https://git-scm.com/) version control system.
-If you haven't, you might also need to install java and curl:
+
+Install java and curl:
 ```shell
+# for Unix systems (Linux and macOS)
 sudo apt install openjdk-11-jdk
 sudo apt install curl
+# for Windows please check online for yourself :)
 ```
 
+Once you have the done previous step, you can continue setting up a virtual
+environment and installing the dependencies. You may as well use your IDE interface
+to set up your venv.
 
-Once you have `conda` and `git` installed, the following commands
-should be typed in your shell in order to download the Ontolearn
-development sources, install the dependencies listened in the
-`environment.yml` into a conda environment and create the necessary
-installation links to get started with the library.
-
-* Download (clone) the source code
+* ->First download (clone) the source code
   ```shell
   git clone https://github.com/dice-group/Ontolearn.git
   cd Ontolearn
   ```
 
-* Create a conda environment using the `environment.yml` file.
-  ```shell
-  conda env create -f environment.yml
-  conda activate ontolearn
-  ```
-* Install the development links so that Python will find the library
+* ->Create a python virtual environment. (We are not using conda anymore)
   ```shell
-  python -c 'from setuptools import setup; setup()' develop 
+  python -m venv venv 
+  source venv/bin/activate # --> for Unix systems
+  # .\venv\Scripts\activate  --> for Windows
   ```
-* Instead of the previous step there is also Possibility B, which is valid temporarily only in your current shell:
+* ->Install the dependencies
   ```shell
-  export PYTHONPATH=$PWD
+  pip install -r requirements.txt
   ```
-
+  
 Now you are ready to develop on Ontolearn or use the library!
 
 ### Verify installation
@@ -82,12 +75,16 @@ to successfully pass all the tests:
 ```shell
 pytest
 ```
+Note: Since Unix and Windows reference files differently, the test are set to work on Linux 
+but in Widows the filepaths throughout test cases should be changed which is something that
+is not very convenient to do. If you really want to run the tests in Windows, you can
+make use of the replace all functionality to change them.
 
 ## Download External Files
 
 Some resources like pre-calculated embeddings or `pre_trained_agents` and datasets (ontologies)
 are not included in the repository directly. Use the command line command `wget`
- to download them from our data server.
+to download them from our data server.
 
 > **NOTE: Before you run this commands in your terminal, make sure you are 
 in the root directory of the project!**
@@ -133,10 +130,11 @@ rm -f NCESData.zip
 
 ## Building (sdist and bdist_wheel)
 
-In order to create a *distribution* of the Ontolearn source code, typically when creating a new release, it is necessary to use the `build` tool. It can be invoked with:
+In order to create a *distribution* of the Ontolearn source code, typically when creating a new release, 
+it is necessary to use the `build` tool. It can be invoked with:
 
 ```shell
-tox -e build
+python -m build
 ```
 
 from the main source code folder. Packages created by `build` can then
@@ -149,14 +147,14 @@ be uploaded as releases to the [Python Package Index (PyPI)](https://pypi.org/)
 The documentation can be built with
 
 ```shell
-tox -e docs
+sphinx-build -M html docs/ docs/_build/
 ```
 
 It is also possible to create a PDF manual, but that requires LaTeX to
 be installed:
 
 ```shell
-tox -e docs latexpdf
+sphinx-build -M latex docs/ docs/_build/
 ```
 
 ## Simple Linting