Add documentation

.github/workflows/BuildMKDocsAndPublishToGithubPages.yml

@@ -0,0 +1,51 @@
+# GeoSight is UNICEF's geospatial web-based business intelligence platform.
+#
+# Contact : geosight-no-reply@unicef.org
+#
+# .. note:: This program is free software; you can redistribute it and/or modify
+#    it under the terms of the GNU Affero General Public License as published by
+#    the Free Software Foundation; either version 3 of the License, or
+#    (at your option) any later version.
+#
+# __author__ = 'irwan@kartoza.com'
+# __date__ = '13/06/2023'
+# __copyright__ = ('Copyright 2023, Unicef')
+
+name: 📖 Documentation
+on:
+  push:
+    branches:
+      - main
+      - docs
+    # Paths can be used to only trigger actions when you have edited certain files, such as a file within the /docs directory
+    paths:
+      - ".github/workflows/BuildMKDocsAndPublishToGithubPages.yml"
+      - "docs/**.md"
+      - "docs/**.py"
+      - "docs/assets/**"
+  # Allow manually running in the actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main from github
+        uses: actions/checkout@v1
+      - name: Create Mkdocs Config 🚀
+        working-directory: ./docs
+        run: ./create-mkdocs-html-config.sh
+      - name: Deploy docs to github pages
+        # This is where we get the material theme from
+        uses: timlinux/mkdocs-deploy-gh-pages@master
+        # Wrong
+        #uses: timlinux/QGISAnimationWorkbench@main
+        env:
+          # Read this carefully:
+          # https://github.com/marketplace/actions/deploy-mkdocs#building-with-github_token
+          # The token is automatically generated by the GH Action
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BASE_DIRECTORY: docs
+          CONFIG_FILE: docs/mkdocs.yml
+          REQUIREMENTS: docs/requirements.txt

.github/workflows/tests.yaml

@@ -68,6 +68,7 @@ jobs:
           make dev-runserver
           make dev-load-demo-data
           make sleep
+
       # TODO:
       #  Fix this after we have the tests
       #      - name: Test django endpoint

Makefile

@@ -55,7 +55,8 @@ dev-test:
 	@echo "Run tests"
 	@echo "------------------------------------------------------------------"
 	@docker-compose exec -T dev python manage.py collectstatic --noinput
-	@docker-compose exec -T dev python manage.py test --keepdb --noinput
+	@docker-compose exec -T dev python manage.py test cloud_native_gis.tests --keepdb --noinput
+# TODO: Remove cloud_native_gis.tests by fixing issue https://github.com/kartoza/CloudNativeGIS/issues/7
 
 serve:
 	@echo

README.md

@@ -1 +1,119 @@
-# Kartoza Cloud Native GIS
+# Cloud Native GIS
+
+[![Tests](https://github.com/kartoza/CloudNativeGIS/workflows/Tests/badge.svg)](https://github.com/kartoza/CloudNativeGIS/actions/workflows/tests.yaml)
+
+## Overview
+
+Cloud Native GIS is a platform for handling layers and served on map.
+
+## Key Concepts
+
+**Layer** can be in vector and raster and being served as tile.
+
+**Style** is saved in database. Vector layer is in mapbox style.
+
+**Maputnik** is being used to change the style.
+
+## Quick installation
+
+### Production
+
+```
+git submodule update
+git clone https://github.com/kartoza/CloudNativeGIS
+cp deployment/.template.env deployment/.env
+cp deployment/docker-compose.override.template deployment/docker-compose.template
+make up
+```
+
+The web will be available at `http://127.0.0.1/`
+
+To stop containers:
+
+```
+make kill
+```
+
+To stop and delete containers:
+
+```
+make down
+```
+
+### Development
+
+```
+git submodule update
+git clone https://github.com/kartoza/CloudNativeGIS
+cp deployment/.template.env deployment/.env
+cp deployment/docker-compose.override.template deployment/docker-compose.template
+```
+
+After that, do
+
+- open new terminal
+- on folder root of project, do
+
+```
+make serve
+```
+
+Wait until it is done
+when there is sentence "webpack xxx compiled successfully in xxx ms".<br>
+After that, don't close the terminal.
+If it is accidentally closed, do `make serve` again
+
+Next step:
+
+- Open new terminal
+- Do commands below
+
+```
+make up
+make dev
+```
+
+Wait until it is on.
+
+The web can be accessed using `http://localhost:5000/`
+
+If the web is taking long time to load, restart geosight_dev container.<br>
+The sequence should be `make dev`, after that run or restart geosight_dev.
+
+### Maputnik updates
+
+CloudNativeGIS using maputnik to edit style.
+We could update maputnik in the folder root/maputnik.
+Maputnik can be accessed in the django-admin and layers, and there is "editor"
+column that will be redirect to maputnik instance.
+By default, it is using maputnik production.
+
+To change and test maputnik:
+
+```
+make serve-maputnik
+```
+
+After it is done, there will be link to maputnik.
+Copy the link and paste in:
+go to deployment/.env
+change MAPUTNIK_URL to the copied link
+
+```
+restart dev container
+```
+
+After done, we need to update the maputnik production.<br>
+First, create commit of maputnik and push it to repo.
+Then
+
+```
+make build-maputnik
+```
+
+It will create files in the
+django_project/cloud_native_gis/templates/maputnik.html
+and also assets in the django_project/cloud_native_gis/static
+
+After that, test it by remove MAPUTNIK_URL and restart dev container.
+If satisfied, just create commit for the changes.

deployment/.template.env

@@ -19,3 +19,4 @@ REDIS_PASSWORD=redis_password
 RABBITMQ_HOST=rabbitmq
 SENTRY_DSN=
 SECRET_KEY=SECRET_KEY
+MAPUTNIK_URL=

deployment/docker-compose.override.template.yml

@@ -61,6 +61,7 @@ services:
       - DATABASE_PASSWORD=${DATABASE_PASSWORD:-docker}
       - DATABASE_HOST=${DATABASE_HOST:-db}
       - DJANGO_SETTINGS_MODULE=core.settings.dev
+      - MAPUTNIK_URL=${MAPUTNIK_URL}
 
       # Email where alters should be sent. This will be used by let's encrypt and as the django admin email.
       - ADMIN_USERNAME=${ADMIN_USERNAME:-admin}

django_project/cloud_native_gis/utils/layer.py

@@ -12,7 +12,10 @@
 def maputnik_url() -> str:
     """Return url for mapnik layer."""
     try:
-        return os.environ['MAPUTNIK_URL']
+        maputnik_url = os.environ['MAPUTNIK_URL']
+        if not maputnik_url:
+            raise KeyError()
+        return maputnik_url
     except KeyError:
         return reverse('cloud-native-gis-maputnik')
 

docs/.envrc

@@ -0,0 +1,2 @@
+use nix
+layout python

docs/.gitignore

@@ -0,0 +1,15 @@
+.idea
+.venv
+pdfs/
+
+# mkdocs related
+mkdocs.yml
+templates/graphics.scss
+site/*
+
+#direnv for docs building
+.direnv
+# Autogenerated api docs
+src/developer/manual/*.md
+
+*.swp