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

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 are willing to see this feature land in the functional perimeter, don't hesitet 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 meanwhile, it's not a blocking lack, since QDT support 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 perform the intermediary git pull, it depends on the organization and GIS team habits. It can be performed manually through the command-line, with a GUI like the excellent [GitHub Desktop](https://github.com/apps/desktop) or with a script. We give below an example in PowerShell for Windows.
+
+:::{info}
+This script is a sample and might not comply with your environment and/or IT policy. If you intend to use it in production, take time to review it before. If you improve or fix it, please share it.
+:::
+
+```{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..."
+    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'..."
+
+        # 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..."
+
+        # 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
+}