add(docs): how to make QDT work with private git repositories (#634)

Render:


![image](https://github.com/user-attachments/assets/aff84b97-5835-4bdb-b1be-f24261c41979)

Author: Guts

.vscode/settings.json

@@ -80,5 +80,9 @@
         "MD024": {
             "allow_different_nesting": true
         },
-    }
+    },
+    "markdown-mermaid.languages": [
+        "mermaid",
+        "{mermaid}"
+    ]
 }

docs/conf.py

@@ -158,6 +158,7 @@
 }
 
 # mermaid
+mermaid_d3_zoom = True
 mermaid_params = [
     "--theme",
     "forest",
@@ -166,7 +167,7 @@
     "--backgroundColor",
     "transparent",
 ]
-mermaid_d3_zoom = True
+mermaid_version = "11.6.0"
 
 # MyST Parser
 myst_enable_extensions = [

docs/guides/howto_manage_private_git.md

@@ -0,0 +1,37 @@
+# How to make QDT work with a private Git repository
+
+For now, QDT does not support private Git repositories. It's a "to be funded" issue. If you'd like to see this feature included in our functional scope, please don't hesitate to get in touch!
+
+```{mermaid}
+---
+title: QDT workflow around a Git private forge (to be funded)
+---
+
+flowchart LR
+    A["QGIS/QDT admin"] <---> |"classic git workflow<br/>clone/pull & git push"| D(("Private Git repository<br/>i.e. git.myorg.com or on GitHub/Lab"))
+    D --->|"QDT"| F["QGIS end-user<br/>profiles"]
+```
+
+In the meantime, this isn't a critical limitation, as QDT supports local git repositories, i.e. stored on a network drive. Here comes a diagram illustrating the typical workflow used by most of end-users:
+
+```{mermaid}
+---
+title: QDT workflow around a Git private forge (workaround)
+---
+
+flowchart LR
+    A["QGIS/QDT admin"] <---> |"classic git workflow<br/>clone/pull & git push"| D(("Private Git repository<br/>i.e. git.myorg.com or on GitHub/Lab"))
+    D -->|"Pull<br/>(with deployment token)"| E[["Server on local network<br/>i.e. '//gis/software/qgis/qdt/profiles/'"]]
+    E --->|"QDT"| F["QGIS end-user<br/>profiles"]
+```
+
+To execute the intermediate git pull, the approach depends on the organization and GIS team habits. This can be done manually through the command-line, with a GUI like the excellent [GitHub Desktop](https://github.com/apps/desktop) or with a script. Below is an example PowerShell script for Windows.
+
+:::{info}
+This script is provided as a sample and may not fully comply with your environment or IT policies. Before implementing in production, take time to review and test it in your environment. If you make improvements or fixes, please share them.
+:::
+
+```{eval-rst}
+.. literalinclude:: ../../scripts/qdt_clone_pull_profiles.ps1
+  :language: powershell
+```

requirements/documentation.txt

@@ -4,13 +4,13 @@
 furo==2024.*
 matplotlib>=3.8.2,<4
 myst-parser[linkify]>=2,<5
-sphinx-argparse-cli>=1,<2
+sphinx-argparse-cli>=1.19,<2
 sphinx-autobuild==2024.*
 sphinx-copybutton<1
-sphinx-design>=0.5,<1
-sphinxcontrib-mermaid>=0.9,<2
-sphinxext-opengraph>=0.4,<1
-sphinx-sitemap>=2.4,<3
+sphinx-design>=0.6.1,<1
+sphinxcontrib-mermaid>=1,<2
+sphinxext-opengraph>=0.10,<1
+sphinx-sitemap>=2.6,<3
 
 # -- 'HIDDEN' dependencies, used during CI
 # pip-licenses<5

scripts/qdt_clone_pull_profiles.ps1

@@ -0,0 +1,90 @@
+<#
+.SYNOPSIS
+    Clone or update a Git repository to a network location specified through an environment variable.
+
+.DESCRIPTION
+    This script clones a remote Git repository to a directory specified by an environment variable.
+    If the repository already exists locally, it performs a `git pull` to update it.
+
+.LICENSE
+    SPDX-License-Identifier: MIT
+#>
+
+# -- VARIABLES --
+
+# Default value if the environment variable is not set
+$basePath = if ($env:QDT_LOCAL_CLONE_PROFILES_PATH) { $env:QDT_LOCAL_CLONE_PROFILES_PATH } else { "$env:USERPROFILE\GitRepositories\qdt-qgis-profiles" };
+
+# Remote Git repository URL
+$gitRepo = if ($env:QDT_REMOTE_PROFILES_GIT) { $env:QDT_REMOTE_PROFILES_GIT} else { "https://github.com/qgis-deployment/qgis-deployment-toolbelt-cli.git" };
+
+# Target folder for the local repository
+$repoName = $gitRepo.Split("/")[-1].Replace(".git", "")
+$repoPath = Join-Path -Path $basePath -ChildPath $repoName
+
+
+# -- FUNCTIONS --
+function Test-GitInstalled {
+    try {
+        # Check if Git is installed and operational
+        $gitVersion = git --version 2>&1
+        if ($gitVersion -match "git version") {
+            Write-Host "Git is installed: $gitVersion" -ForegroundColor Green
+            return $true
+        } else {
+            Write-Host "Git is installed but not operational." -ForegroundColor Yellow
+            return $false
+        }
+    } catch {
+        Write-Host "Git is not installed or not found in the PATH." -ForegroundColor Red
+        return $false
+    }
+}
+
+# -- MAIN --
+
+# Check if Git is installed
+if (-not (Test-GitInstalled)) {
+    Write-Error "Git is required for this script. Please install Git and ensure it is in your PATH."
+    exit 1
+}
+
+# Ensure the base directory exists, create it if necessary
+if (-not (Test-Path -Path $basePath)) {
+    Write-Host "The directory '$basePath' does not exist. Creating it..." -ForegroundColor Yellow
+    New-Item -ItemType Directory -Path $basePath | Out-Null
+}
+
+
+# Perform git clone or pull
+try {
+    # Check if the repository already exists locally
+    if (Test-Path -Path $repoPath) {
+        Write-Host "Repository already exists locally at $repoPath. Performing 'git pull'..." -ForegroundColor Cyan
+
+        # Change to the repository directory
+        Push-Location -Path $repoPath
+
+        # Pull the latest changes
+        git fetch --all
+        git reset --hard origin/main
+        # $pullResult = git pull
+        # Write-Host $pullResult
+
+        # Return to the original directory
+        Pop-Location
+    } else {
+        Write-Host "No Git repository identified. Cloning remote repository to $repoPath..." -ForegroundColor Cyan
+
+        # Clone the repository
+        git clone --config remote.origin.pushurl="DISABLED" `
+                  --depth=5 `
+                  $gitRepo `
+                  $repoPath
+    }
+
+    Write-Host "Operation completed successfully!" -ForegroundColor Green
+} catch {
+    Write-Error "An error occurred: $_"
+    exit 1
+}