Merge pull request #433 from hotosm/docs/mkdocs

Docs/mkdocs

.github/workflows/main.yml

@@ -1,50 +1,25 @@
-# This is a basic workflow to help you get started with Actions
-
-name: Doxygen Action
-
-# Controls when the action will run. 
+name: Docs Action
 on:
   push:
-    branches: [ master ]
-
-# A workflow run is made up of one or more jobs that can run
-# sequentially or in parallel
+    branches:
+      - master 
+      - main
+permissions:
+  contents: write
 jobs:
-  # This workflow contains a single job called "build"
-  build:
-    # The type of runner that the job will run on
-    runs-on: ubuntu:kinetic
-    # Steps represent a sequence of tasks that will be executed
-    # as part of the job
+  deploy:
+    runs-on: ubuntu-latest
     steps:
-    # Checks-out your repository under $GITHUB_WORKSPACE, so your
-    # job can access it
-    - uses: actions/checkout@v2
-
-    - name: Start Docker Compose
-      run: cd docker && docker-compose up -d
-
-    - name: Create Doxyfile
-      run: docker-compose -f docker-compose.yml exec -T underpass sh -c "cd /code && ./autogen.sh && ./configure && make docs/Doxyfile -j `nproc`"
-
-    - name: Doxygen Action
-      uses: mattnotmitt/doxygen-action@v1.1.0
-      with:
-          doxyfile-path: ./docs/Doxyfile
-          working-directory: .
-
-    - name: Debug
-      run: ls -la ./html
-
-    - name: Deploy HTML
-      uses: peaceiris/actions-gh-pages@v3
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./html
-        publish_branch: gh-pages
-
-  on-failure:
-    runs-on: ubuntu-20.04
-    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
-    steps:
-      - run: echo 'The docker build workflow failed'
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

.github/workflows/run_tests.yml

@@ -6,7 +6,7 @@ jobs:
 
   build:
 
-    runs-on: ubuntu:kinetic
+    runs-on: ubuntu-latest
 
     steps:
 

docs/docs/API/Python.md

@@ -0,0 +1,18 @@
+## Call Underpass functions using Python C++ binding
+
+### Import Underpass package
+
+```py
+    import underpass as u
+```
+
+### Validate OSM Change
+
+```py
+    with open("building.osc", 'r') as file:
+        data = file.read().rstrip()
+
+    validator = u.Validate()
+    result = validator.checkOsmChange(data, "building")
+```
+

docs/docs/API/PythonDB.md

@@ -0,0 +1,172 @@
+## Get data from the Underpass DB using Python
+
+### Connect to the database
+
+```py
+from api.db import UnderpassDB`
+db = UnderpassDB("postgresql://localhost/underpass")
+db.connect()
+```
+
+### Get raw data 
+
+```py
+from api import raw
+rawer = raw.Raw(db)
+```
+
+#### Get polygons
+
+```py
+polygons = rawer.getPolygons( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building=yes",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+```
+
+#### Get lines
+
+```py
+lines = rawer.getLines( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "highway",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+```
+
+
+#### Get nodes
+
+```py
+nodes = rawer.getNodes( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "amenity",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+```
+
+#### Get all together (polygons, lines and nodes)
+
+```py
+nodes = rawer.getAll( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+```
+
+#### Get list of polygons
+
+```py
+polygons = rawer.getPolygonsList( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+```
+
+#### Get list of lines
+
+```py
+lines = rawer.getLinesList( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+```
+
+#### Get list of nodes
+
+```py
+nodes = rawer.getNodesList( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+```
+
+#### Get list of all together (polygons, lines and nodes)
+
+```py
+all = rawer.getAllList( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+```
+
+### Get data quality reports in CSV or GeoJSON
+
+```py
+from api import report
+reporter = report.Report(db)
+```
+
+#### Get report for geometries
+
+```py
+results = reporter.getDataQualityGeo(
+    fromDate = "2022-12-28T00:00:00", 
+    hashtags = ["hotosm"],
+    responseType = "csv"
+)
+```
+
+#### Get latest results for geometries
+
+```py
+results = reporter.getDataQualityGeoLatest()
+```
+
+For getting results in CSV format, instead of GeoJSON
+
+```py
+results = reporter.getDataQualityGeoLatest(
+    responseType = "csv"
+)
+```
+
+#### Get report for tags
+
+```py
+results = reporter.getDataQualityTag(
+    fromDate = "2022-12-28T00:00:00", 
+    hashtags = ["hotosm"],
+    responseType = "csv"
+)
+```
+
+#### Get statistics for tags
+
+```py
+results = reporter.getDataQualityTagStats(
+    fromDate = "2022-12-28T00:00:00", 
+    hashtags = ["hotosm"],
+    responseType = "csv"
+)
+```

docs/docs/API/REST.md

@@ -0,0 +1,125 @@
+## Run a RESTful API
+
+### Setup & run
+
+#### Install requirements
+
+```sh
+cd python/restapi/ && pip install -r requirements.txt
+```
+
+#### Setup DB connection
+
+Set the database connection string as an environment variable:
+
+```sh
+export UNDERPASS_API_DB=postgresql://localhost/underpass
+```
+
+#### Run
+
+```sh
+uvicorn main:app --reload 
+```
+
+### Making queries
+
+#### Raw data
+
+#### Get polygons
+
+```sh
+curl http://localhost:8000/raw/polygons -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "building=yes"}'
+```
+
+#### Get lines
+
+```sh
+curl http://localhost:8000/raw/lines -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "highway"}'
+```
+
+#### Get nodes
+
+```sh
+curl http://localhost:8000/raw/nodes -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "amenity"}'
+```
+
+#### Get all together (polygons, lines and nodes)
+
+```sh
+curl http://localhost:8000/raw/all -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "building"}'
+```
+
+#### Get list of polygons
+
+```sh
+curl http://localhost:8000/raw/polygonsList -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "building=yes"}'
+```
+
+#### Get list of lines
+
+```sh
+curl http://localhost:8000/raw/linesList -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "highway"}'
+```
+
+#### Get list of nodes
+
+```sh
+curl http://localhost:8000/raw/nodesList -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "amenity"}'
+```
+
+#### Get list of all together (polygons, lines and nodes)
+
+```sh
+curl http://localhost:8000/raw/allList -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "building"}'
+```
+
+### Get data quality reports in CSV or GeoJSON
+
+#### Get report for geometries
+
+```sh
+curl http://localhost:8000/report/dataQualityGeo -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"fromDate":"2022-12-28T00:00:00", "hashtags": "hotosm"}'
+```
+
+In CSV format instead of GeoJSON:
+
+```sh
+curl http://localhost:8000/report/dataQualityGeo/csv -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"fromDate":"2022-12-28T00:00:00", "hashtags": "hotosm"}'
+```
+
+#### Get report for tags
+
+```sh
+curl http://localhost:8000/report/dataQualityTags -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"fromDate":"2022-12-28T00:00:00", "hashtags": "hotosm"}'
+```
+
+#### Get statistics for tags
+
+```sh
+curl http://localhost:8000/report/dataQualityTagStats -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"fromDate":"2022-12-28T00:00:00", "hashtags": "hotosm"}'
+```