Merge pull request #1 from shnmrt/main

working version of the saferoad

Author: shnmrt

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: Build & Deploy Docs
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install depdencies
+        run: |
+          python -m pip install -U pip
+          pip install .
+          pip install sphinx sphinx-rtd-theme
+
+      - name: Build Docs
+        run: sphinx-build -b html docs/source docs/_build/html
+      - name: add .nojekyll
+        run: touch docs/_build/html/.nojekyll
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html
+          publish_branch: gh-pages
+          force_orphan: true

.github/workflows/tests.yml

@@ -0,0 +1,35 @@
+name: Test CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+          python -c "import duckdb; duckdb.install_extension('spatial')"
+          pip install coverage
+
+      - name: Run unittests with coverage
+        run: |
+          coverage run -m tests
+          coverage report -m --omit="tests/*"

README.md

@@ -1 +1,51 @@
-# SafeRoads
+# SafeRoad
+
+## About
+
+**SafeRoad** is an open-source Python library designed to monitor the structural condition of the road network by providing tools for data analysis and visualisation.
+It aims to assist researchers, policymakers, and developers in understanding and mitigating structural safety issues of road networks.
+**SafeRoad** is built with a focus on usability, performance, and extensibility. It uses modern Python libraries such as [duckdb](https://duckdb.org/),
+[shapely](https://shapely.readthedocs.io/en/stable/), [matplotlib](https://matplotlib.org/) and [contextily](https://contextily.readthedocs.io/en/latest/) to provide a robust framework for road network safety analyses.
+
+You can access the more detailed description of the methodology from the [paper](https://doi.org/10.1177/14759217211045912).
+
+The library is modular, user-friendly, and well-documented, making it suitable for both beginners and experts in the field of structural safety.
+
+## Installation
+
+1. Create a virtual environment and activate it
+
+```bash
+# conda
+conda create --name saferoad_env python=3.10
+# activate environment
+conda activate saferoad_env
+```
+
+2. Clone the reposity to your current directory
+
+```bash
+git clone https://github.com/SafeStruct/SafeRoad.git
+```
+
+3. Install the library from directory using pip
+
+```bash
+pip install -e ./SafeRoad
+```
+
+4. Testing the installation using tutorial
+
+```bash
+# before testing one extension needs to be installed
+python -c "import duckdb; duckdb.install_extension('spatial')"
+# change the directory to examples and run the tutorial
+cd SafeRoad/examples
+python tutorial.py
+```
+
+If everything works correctly, you should see a folder called **`SafeRoadDB`** inside the example folder. Inside that folder, you will find the generated **PDF** report for the entire dataset provided.
+
+# Disclaimer
+
+The Multi-Temporal SAR data provided in the repository is not real; it is synthetic. It is produced to demonstrate how the tool works and what kind of report it generates.

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     = source
+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)