Update doc tasks and scripts (w. GitHub Pages)

.vscode/tasks.json

@@ -291,7 +291,7 @@
             }
         },
         {
-            "label": "Build documentation",
+            "label": "Build PDF documentation",
             "type": "shell",
             "command": "cmd",
             "options": {
@@ -321,7 +321,7 @@
             }
         },
         {
-            "label": "Build HTML documentation",
+            "label": "HTML documentation: quick preview",
             "type": "shell",
             "command": "cmd",
             "options": {
@@ -350,6 +350,104 @@
                 "clear": true
             }
         },
+        {
+            "label": "GitHub Pages: build",
+            "type": "shell",
+            "command": "cmd",
+            "options": {
+                "cwd": "scripts",
+                "env": {
+                    "PYTHON": "${env:CDL_PYTHONEXE}",
+                    "QT_COLOR_MODE": "light",
+                    "UNATTENDED": "1"
+                }
+            },
+            "args": [
+                "/c",
+                "build_ghpages.bat"
+            ],
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "shared",
+                "showReuseMessage": true,
+                "clear": true
+            }
+        },
+        {
+            "label": "GitHub Pages: preview",
+            "type": "shell",
+            "command": "cmd",
+            "options": {
+                "cwd": "scripts",
+                "env": {
+                    "PYTHON": "${env:CDL_PYTHONEXE}",
+                    "QT_COLOR_MODE": "light",
+                    "UNATTENDED": "1"
+                }
+            },
+            "args": [
+                "/c",
+                "preview_ghpages.bat"
+            ],
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "shared",
+                "showReuseMessage": true,
+                "clear": true
+            },
+            "dependsOrder": "sequence",
+            "dependsOn": [
+                "GitHub Pages: build"
+            ]
+        },
+        {
+            "label": "GitHub Pages: upload",
+            "type": "shell",
+            "command": "cmd",
+            "options": {
+                "cwd": "scripts",
+                "env": {
+                    "PYTHON": "${env:CDL_PYTHONEXE}",
+                    "QT_COLOR_MODE": "light",
+                    "UNATTENDED": "1"
+                }
+            },
+            "args": [
+                "/c",
+                "upload_ghpages.bat"
+            ],
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "shared",
+                "showReuseMessage": true,
+                "clear": true
+            },
+            "dependsOrder": "sequence",
+            "dependsOn": [
+                "GitHub Pages: build"
+            ]
+        },
         {
             "label": "Build Python packages",
             "type": "shell",

doc/conf.py

@@ -24,6 +24,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.mathjax",
+    "sphinx.ext.githubpages",
     "myst_parser",
     "sphinx_design",
 ]

scripts/build_doc_html.bat

@@ -24,7 +24,7 @@ mkdir %MODNAME%\data\doc
 @REM Build documentation ===============================================================
 set LANG=fr
 if exist build\doc ( rmdir /s /q build\doc )
-sphinx-build -b html -D language=fr doc build\doc
+sphinx-build -b html -D language=%LANG% doc build\doc
 start build\doc\index.html
 
 call %FUNC% EndOfScript

scripts/build_ghpages.bat

@@ -0,0 +1,47 @@
+@echo off
+REM This script was copied from PythonQwt project
+REM ======================================================
+REM Build GitHub Pages documentation
+REM ======================================================
+REM Licensed under the terms of the MIT License
+REM Copyright (c) 2020 Pierre Raybaut
+REM (see PythonQwt LICENSE file for more details)
+REM ======================================================
+
+@REM Get the target path for GitHub Pages from `CDL_GHPAGES` environment variable:
+@REM if this variable is not defined, interrupt the script and show an error message
+if not defined CDL_GHPAGES (
+    echo ERROR: CDL_GHPAGES environment variable is not defined.
+    echo Please define it to the path of the local clone of the GitHub Pages repository.
+    echo For instance:
+    echo     set CDL_GHPAGES=C:\Dev\DataLab_GitHub_Pages
+    echo.
+    echo Then, run this script again.
+    exit /b 1
+)
+
+call %~dp0utils GetScriptPath SCRIPTPATH
+call %FUNC% GetLibName LIBNAME
+call %FUNC% GetModName MODNAME
+call %FUNC% SetPythonPath
+call %FUNC% UsePython
+call %FUNC% GetVersion CDL_VERSION
+
+cd %SCRIPTPATH%\..
+%PYTHON% doc\update_requirements.py
+
+@REM Set light mode for Qt applications and clean previous documentation ===============
+set QT_COLOR_MODE=light
+if exist %MODNAME%\data\doc ( rmdir /s /q %MODNAME%\data\doc )
+mkdir %MODNAME%\data\doc
+
+@REM Build documentation ===============================================================
+for %%L in (fr en) do (
+    set LANG=%%L
+    %PYTHON% doc/update_screenshots.py
+    set TARGET=%CDL_GHPAGES%\%%L
+    if exist %TARGET% ( rmdir /s /q %TARGET% )
+    sphinx-build -b html -D language=%%L doc %TARGET%
+)
+
+call %FUNC% EndOfScript

scripts/preview_ghpages.bat

@@ -0,0 +1,20 @@
+@echo off
+REM This script was copied from PythonQwt project
+REM ======================================================
+REM Preview GitHub Pages documentation
+REM ======================================================
+REM Licensed under the terms of the MIT License
+REM Copyright (c) 2020 Pierre Raybaut
+REM (see PythonQwt LICENSE file for more details)
+REM ======================================================
+
+call %~dp0utils GetScriptPath SCRIPTPATH
+call %FUNC% SetPythonPath
+call %FUNC% UsePython
+
+start http://localhost:8000
+
+cd %CDL_GHPAGES%
+%PYTHON% -m http.server
+
+call %FUNC% EndOfScript

scripts/upload_ghpages.bat

@@ -0,0 +1,32 @@
+@echo off
+REM This script was copied from PythonQwt project
+REM ======================================================
+REM Upload GitHub Pages documentation
+REM ======================================================
+REM Licensed under the terms of the MIT License
+REM Copyright (c) 2020 Pierre Raybaut
+REM (see PythonQwt LICENSE file for more details)
+REM ======================================================
+
+@REM Get the target path for GitHub Pages from `CDL_GHPAGES` environment variable:
+@REM if this variable is not defined, interrupt the script and show an error message
+if not defined CDL_GHPAGES (
+    echo ERROR: CDL_GHPAGES environment variable is not defined.
+    echo Please define it to the path of the local clone of the GitHub Pages repository.
+    echo For instance:
+    echo     set CDL_GHPAGES=C:\Dev\DataLab_GitHub_Pages
+    echo.
+    echo Then, run this script again.
+    exit /b 1
+)
+
+call %~dp0utils GetScriptPath SCRIPTPATH
+
+pushd %CDL_GHPAGES%
+git checkout gh-pages
+git add .
+git commit -m "Update documentation"
+git push origin gh-pages
+popd
+
+call %FUNC% EndOfScript