Merge pull request #118 from unicef/feature/documentation

add ! docs

.github/file-filters.yml

@@ -37,3 +37,9 @@ lint:
   -  *python
   - '.flake8'
   - 'pyproject.toml'
+
+docs:
+  - added|modified: './docs/**/*'
+  - modified: './src/hope_dedup_engine/config/__init__.py'
+  - modified: './github/workflows/docs.yml'
+  - modified: './github/file-filters.yml'

.github/workflows/docs.yml

@@ -0,0 +1,83 @@
+name: "Documentation"
+
+on:
+  push:
+    branches:
+      - develop
+      - master
+  schedule:
+    - cron: '37 23 * * 2'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    defaults:
+      run:
+        shell: bash
+    outputs:
+      docs: ${{ steps.changed_files.outputs.docs }}
+    steps:
+      - name: Checkout code
+        uses: actions/[email protected]
+      - id: changed_files
+        name: Check for file changes
+        uses: dorny/paths-filter@0bc4621a3135347011ad047f9ecf449bf72ce2bd # v3.0.0
+        with:
+          base: ${{ github.ref }}
+          token: ${{ github.token }}
+          filters: .github/file-filters.yml
+  generate:
+    name: Generate
+    if: needs.changes.outputs.docs == 'true'
+    needs: changes
+    runs-on: ubuntu-latest
+    env:
+      PYTHONPATH: src/
+    steps:
+      - uses: actions/checkout@v4
+      - uses: yezz123/setup-uv@v4
+
+      - uses: actions/cache/restore@v4
+        id: restore-cache
+        with:
+          path: .venv
+          key: ${{ runner.os }}-${{ hashFiles('**/uv.lock') }}
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Build Doc
+        run: .venv/bin/mkdocs build -d ./docs-output
+
+      - uses: actions/cache/save@v4
+        id: cache
+        if: always() && steps.restore-cache.outputs.cache-hit != 'true'
+        with:
+          path: .venv
+          key: ${{ runner.os }}-${{ hashFiles('**/uv.lock') }}
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs-output
+
+  # Deployment job
+  deploy:
+    needs: generate
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/_hooks/hooks.py

@@ -0,0 +1,24 @@
+# mypy: disable-error-code="typeddict-unknown-key"
+from datetime import datetime
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import Files
+from mkdocs.structure.nav import Navigation
+from mkdocs.structure.pages import Page
+from mkdocs.utils.templates import TemplateContext
+
+
+def on_pre_build(config: MkDocsConfig) -> None:
+    pass
+
+
+def on_page_markdown(
+    markdown: str, page: Page, config: MkDocsConfig, files: Files
+) -> None:
+    pass
+
+
+def on_page_context(
+    context: TemplateContext, nav: Navigation, page: Page, config: MkDocsConfig
+) -> None:
+    context["build_date"] = datetime.now().strftime("%a, %d, %b %Y - %H:%M")

docs/_scripts/get_settings.py

@@ -0,0 +1,40 @@
+import mkdocs_gen_files
+
+from hope_dedup_engine.config import env
+
+MD_HEADER = """# Setttings
+
+"""
+MD_LINE = """
+### {key}
+_Default_: `{default_value}`
+
+{help}
+
+"""
+DEV_LINE = """
+__Suggested value for development__: `{develop_value}`
+"""
+
+OUTFILE = "settings.md"
+with mkdocs_gen_files.open(OUTFILE, "w") as f:
+    f.write(MD_HEADER)
+    for entry, cfg in sorted(env.config.items()):
+        f.write(
+            MD_LINE.format(
+                key=entry,
+                default_value=cfg["default"],
+                develop_value=env.get_develop_value(entry),
+                help=cfg["help"],
+            )
+        )
+        if env.get_develop_value(entry):
+            f.write(
+                DEV_LINE.format(
+                    key=entry,
+                    default_value=cfg["default"],
+                    develop_value=env.get_develop_value(entry),
+                    help=cfg["help"],
+                )
+            )
+mkdocs_gen_files.set_edit_path(OUTFILE, "get_settings.py")

docs/_theme/css/style.scss

@@ -0,0 +1,12 @@
+.align-center{
+  align-content: center;
+  text-align: center;
+  width: 100%;
+}
+.md-typeset__table {
+  width: 100%;
+}
+
+.md-typeset__table table:not([class]) {
+  display: table
+}

docs/_theme/js/address.js

@@ -0,0 +1,50 @@
+const clickHandler = function () {
+    let currentAddr = Cookies.get('address') || "https://127.0.0.1/";
+    let addr = prompt("Set your HOPE server address", currentAddr);
+    Cookies.set('address', addr, currentAddr);
+    location.reload();
+};
+const setAddress = function () {
+    let cookieAddr = Cookies.get('address');
+    if (!cookieAddr) {
+        cookieAddr = "[SERVER_ADDRESS]"
+    }
+    for (const cell of document.getElementsByTagName('code')) {
+        cell.innerHTML = cell.innerHTML.replace('[SERVER_ADDRESS]', cookieAddr);
+    }
+};
+// addEventListener('click', function(e) {
+//     setTimeout(setAddress, 500);
+// })
+addEventListener('load', function (e) {
+    setAddress();
+    let btn = document.getElementById("set-address");
+    if (btn) {
+        btn.addEventListener('click', clickHandler);
+    }
+});
+
+var open = window.XMLHttpRequest.prototype.open,
+    send = window.XMLHttpRequest.prototype.send, onReadyStateChange;
+
+function sendReplacement(data) {
+    console.warn('Sending HTTP request data : ', data);
+
+    if (this.onreadystatechange) {
+        this._onreadystatechange = this.onreadystatechange;
+    }
+    this.onreadystatechange = onReadyStateChangeReplacement;
+    return send.apply(this, arguments);
+}
+
+function onReadyStateChangeReplacement() {
+    if (this.readyState === XMLHttpRequest.DONE) {
+        setTimeout(setAddress, 100);
+    }
+    if (this._onreadystatechange) {
+        return this._onreadystatechange.apply(this, arguments);
+    }
+
+}
+
+window.XMLHttpRequest.prototype.send = sendReplacement;

docs/_theme/js/js.cookie.js

@@ -0,0 +1,59 @@
+/*! js-cookie v3.0.5 | MIT */
+!function (e, t) {
+    "object" == typeof exports && "undefined" != typeof module ? module.exports = t() : "function" == typeof define && define.amd ? define(t) : (e = "undefined" != typeof globalThis ? globalThis : e || self, function () {
+        var n = e.Cookies, o = e.Cookies = t();
+        o.noConflict = function () {
+            return e.Cookies = n, o
+        }
+    }())
+}(this, (function () {
+    "use strict";
+
+    function e(e) {
+        for (var t = 1; t < arguments.length; t++) {
+            var n = arguments[t];
+            for (var o in n) e[o] = n[o]
+        }
+        return e
+    }
+
+    var t = function t(n, o) {
+        function r(t, r, i) {
+            if ("undefined" != typeof document) {
+                "number" == typeof (i = e({}, o, i)).expires && (i.expires = new Date(Date.now() + 864e5 * i.expires)), i.expires && (i.expires = i.expires.toUTCString()), t = encodeURIComponent(t).replace(/%(2[346B]|5E|60|7C)/g, decodeURIComponent).replace(/[()]/g, escape);
+                var c = "";
+                for (var u in i) i[u] && (c += "; " + u, !0 !== i[u] && (c += "=" + i[u].split(";")[0]));
+                return document.cookie = t + "=" + n.write(r, t) + c
+            }
+        }
+
+        return Object.create({
+            set: r, get: function (e) {
+                if ("undefined" != typeof document && (!arguments.length || e)) {
+                    for (var t = document.cookie ? document.cookie.split("; ") : [], o = {}, r = 0; r < t.length; r++) {
+                        var i = t[r].split("="), c = i.slice(1).join("=");
+                        try {
+                            var u = decodeURIComponent(i[0]);
+                            if (o[u] = n.read(c, u), e === u) break
+                        } catch (e) {
+                        }
+                    }
+                    return e ? o[e] : o
+                }
+            }, remove: function (t, n) {
+                r(t, "", e({}, n, {expires: -1}))
+            }, withAttributes: function (n) {
+                return t(this.converter, e({}, this.attributes, n))
+            }, withConverter: function (n) {
+                return t(e({}, this.converter, n), this.attributes)
+            }
+        }, {attributes: {value: Object.freeze(o)}, converter: {value: Object.freeze(n)}})
+    }({
+        read: function (e) {
+            return '"' === e[0] && (e = e.slice(1, -1)), e.replace(/(%[\dA-F]{2})+/gi, decodeURIComponent)
+        }, write: function (e) {
+            return encodeURIComponent(e).replace(/%(2[346BF]|3[AC-F]|40|5[BDE]|60|7[BCD])/g, decodeURIComponent)
+        }
+    }, {path: "/"});
+    return t
+}));

docs/_theme/overrides/term.html

@@ -0,0 +1,5 @@
+{% extends "base.html" %}
+{%- block content %}
+    <h5><a href="../../">glossary</a> / {{ page.title }}</h5>
+    {{ super() }}
+{%- endblock %}

docs/src/.gitignore

@@ -0,0 +1,3 @@
+!**/.pages
+!.includes
+_theme/.templates

docs/src/.pages

@@ -0,0 +1,9 @@
+nav:
+  - index.md
+  - settings.md
+  - Setup service: setup.md
+  - REST API: API.md
+  - Duplicated Image Detection: did
+  - Troubleshooting: troubleshooting.md
+  - Demo Application: demo.md
+  - Development: development.md

docs/src/API.md

@@ -0,0 +1,17 @@
+The application provides comprehensive API documentation to facilitate ease of use and integration. API documentation is available via two main interfaces:
+
+#### Swagger UI
+An interactive interface that allows users to explore and test the API endpoints. It provides detailed information about the available endpoints, their parameters, and response formats. Users can input data and execute requests directly from the interface.
+
+URL: `http://localhost:8000/api/rest/swagger/`
+
+#### Redoc
+A static, beautifully rendered documentation interface that offers a more structured and user-friendly presentation of the API. It includes comprehensive details about each endpoint, including descriptions, parameters, and example requests and responses.
+
+URL: `http://localhost:8000/api/rest/redoc/`
+
+
+These interfaces ensure that developers have all the necessary information to effectively utilize the API, enabling seamless integration and interaction with the application’s features.
+
+!!! warning "Environment-Specific URLs"
+    The URLs will vary depending on the server where it is hosted. If the server is hosted elsewhere except for the local machine, replace **http://localhost:8000** with the server's domain URL.