recolordocsicons: Add the tool and a README

Move the recolordocsicons.py script from qtcreator to qttools\util.

Change-Id: I64b0ef7204ebe6334527dcd800fa5530bbd0e325
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
(cherry picked from commit 04170761698b298a1d8df2f380d787293ada5635)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit 418d26c029e90d17b0d06a46dd9c313a1c28f097)

2 files changed, 108 insertions, 0 deletions

diff --git a/util/recolordocsicons/README.md b/util/recolordocsicons/README.md
new file mode 100644
index 000000000..44e69cc67
--- /dev/null
+++ b/util/recolordocsicons/README.md
@@ -0,0 +1,32 @@
+How to recolor icons for doc.qt.io
+==================================
+
+You can view Qt Documentation online at https://doc.qt.io in dark and light
+modes. To make the icons you use in the docs visible in both modes, save icon
+files as gray-scale images with a transparent background.
+
+If you receive a large number of icons that are not visible in either light
+or dark mode or have a solid background, run the ``recolordocsicons.py``
+Python script.
+
+The script runs ImageMagick to recolor the images and optipng to optimize the
+icon files.
+
+## Preparation
+
+To run the script, you will need to install the following tools and add them
+to the PATH:
+
+- Python 3.x (the script has been tested to work with 3.10)
+- ImageMagick
+- optipng
+
+## Running the script
+
+Use the `-docspath` option to specify the path to the folder where you stored
+the icons.
+
+For example, if you saved the new icons in `C:\iconconversions`, switch to
+the `qttools\util\recolordocsicons` folder and enter:
+
+`recolordocsicons.py -docspath C:\iconconversions`
diff --git a/util/recolordocsicons/recolordocsicons.py b/util/recolordocsicons/recolordocsicons.py
new file mode 100644
index 000000000..70dee2699
--- /dev/null
+++ b/util/recolordocsicons/recolordocsicons.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+
+# Copyright (C) 2022 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
+
+import argparse
+import os
+import pathlib
+import subprocess
+import sys
+
+from distutils import spawn
+
+def recolorizePng(pngPath, color, magick):
+    print("Recolorizing: {}".format(pngPath))
+    try:
+        subprocess.check_call([magick,
+                               pngPath,
+                               "-depth", "24",
+                               "-colorspace", "rgb",
+                               "(", "+clone", "-background", "white", "-flatten", ")",
+                               "(", "+clone", "-negate", "-alpha", "copy", ")",
+                               "(", "+clone", "-fuzz", "100%", "-fill", color, "-opaque", color, ")",
+                               "(", "-clone", "-1,-2", "-compose", "dst_in", "-composite", ")",
+                               "-delete", "0--2",
+                               pngPath])
+    except subprocess.CalledProcessError:
+        sys.exit("Failed to recolorize {}.".format(pngPath))
+
+
+def optimizePng(pngPath, optipng):
+    print("Optimizing: {}".format(pngPath))
+    try:
+        subprocess.check_call([optipng,
+                               "-o7",
+                               "-strip", "all",
+                               pngPath],
+                              stderr=subprocess.DEVNULL)
+    except subprocess.CalledProcessError:
+        sys.exit("Failed to optimize {}.".format(pngPath))
+
+
+def processDocsPath(docsPath, color, magick, optipng):
+    pngPaths = docsPath.glob('**/*.png')
+    for pngPath in pngPaths:
+        recolorizePng(pngPath, color, magick)
+        optimizePng(pngPath, optipng)
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Recolor icon .png files in the '
+                                     'Documentation. '
+                                     'Requires ImageMagick and Optipng in Path.')
+    parser.add_argument('-docspath',
+                        help='The path to process (recursively).',
+                        type=pathlib.Path)
+    parser.add_argument('-color',
+                        help='The icon foreground color.',
+                        default="#808080")
+    args = parser.parse_args()
+
+    magick = spawn.find_executable("magick")
+    if magick is None:
+        sys.exit("ImageMagick was not found in Path.")
+
+    optipng = spawn.find_executable("optipng")
+    if optipng is None:
+        sys.exit("Optipng was not found in Path.")
+
+    processDocsPath(args.docspath, args.color, magick, optipng)
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())