Merge pull request #285 from Living-with-machines/mkdocs

Update docs site & migrate to Material for Mkdocs

.github/workflows/docs.yml

@@ -1,67 +1,29 @@
-name: Docs2Pages
-
-on: [pull_request]
-
+name: docs2pages 
+on:
+  push:
+    branches:
+      - dev
+      - main
+permissions:
+  contents: write
 jobs:
-  run:
+  deploy:
     runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-        python-version: [3.9]
-      fail-fast: false
-
     steps:
-      - uses: actions/checkout@v2
-        with:
-          fetch-depth: 2
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v1
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Bootstrap poetry
-        shell: bash
-        run: |
-          python -m ensurepip
-          python -m pip install --upgrade pip
-          python -m pip install poetry
-
-      - name: Configure poetry
-        shell: bash
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
         run: |
-          python -m poetry config virtualenvs.in-project true
-
-      # - name: Set up cache
-      #   uses: actions/cache@v2
-      #   id: cache
-      #   with:
-      #     path: .venv
-      #     key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
-
-      # - name: Ensure cache is healthy
-      #   if: steps.cache.outputs.cache-hit == 'true'
-      #   shell: bash
-      #   run: timeout 10s python -m poetry run pip --version || rm -rf .venv
-
-      - name: Install dependencies
-        shell: bash
-        run: |
-          python -m poetry install --with docs
-
-      - name: Build documentation
-        run: |
-          mkdir gh-pages
-          touch gh-pages/.nojekyll
-          cd docs/
-          poetry run sphinx-build -b html source _build
-          cp -r _build/* ../gh-pages/
-
-      - name: Deploy documentation
-        # if: ${{ github.event_name == 'push' }}
-        uses: JamesIves/[email protected]
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
         with:
-          branch: gh-pages
-          folder: gh-pages
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocs-material-extensions
+      - run: mkdocs gh-deploy --force

docs/experiments/evaluation.md

@@ -0,0 +1,2 @@
+
+# Evaluation

docs/experiments/index.md

@@ -0,0 +1,35 @@
+# Experiments and evaluation
+
+Follow these steps to reproduce the experiments in our paper.
+
+## 1. Obtain the external resources
+
+Follow the instructions in the "`/getting-started/resources`{.interpreted-text role="doc"}" page in the documentation to obtain the resources required for running the experiments.
+
+## 2. Preparing the data
+
+To create the datasets that we use in the experiments presented in the paper, run the following command from the `./experiments/` folder:
+
+``` bash
+$ python ./prepare_data.py -p ../resources
+```
+
+This script takes care of downloading the LwM and HIPE datasets and format them as needed in the experiments.
+
+## 3. Running the experiments
+
+To run the experiments, run the following script from the `./experiments/` folder:
+
+``` bash
+$ python ./toponym_resolution.py -p ../resources
+```
+
+This script does runs for all different scenarios reported in the experiments in the paper.
+
+## 4. Evaluate
+
+To evaluate the different approaches and obtain a table with results such as the one provided in the paper, go to the `./evaluation/` directory. There, you should clone the [HIPE scorer](https://github.com/hipe-eval/HIPE-scorer). We are using the code version at commit `50dff4e`, and have added the line `return eval_stats` at the end of the `get_results()` function. From `./evaluation/`, run the following script to obtain the results in latex format:
+
+``` bash
+$ python display_results.py
+```