docs: Note Windows build issues, provide steps to resolve

README.md

@@ -7,79 +7,90 @@
 Knut is an automation tool for code transformation using scripts. The main use case is for migration, but it could be used elsewhere.
 
 The scripts are written either in javascript or QML languages, the latter being able to display a user interface to customize some parts of the application.
-The script API is available in this documentation, and ranges from normal text transformations (find and replace) to getting contextual information based on the file language (using [TreeSitter](https://tree-sitter.github.io/tree-sitter/).
+The script API is available in this documentation, and ranges from normal text transformations (find and replace) to getting contextual information based on the file language (using [TreeSitter](https://tree-sitter.github.io/tree-sitter/)).
 
 Knut can be used via a command line interface or a user interface.
 
-# Requirements
+## Requirements
 
 Knut is using [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) servers for the GUI. It is not used for the scripts, so if you are using Knut with the command line interface, you don't need it.
 
 For C++, if you are using clangd, note that some tests are disabled for clangd version < 13.
 
-# Licensing
+## Licensing
 
 Knut is © Klarälvdalens Datakonsult AB (KDAB) and is licensed according to the terms of [GPL 3.0](LICENSES/GPL-3.0-only.txt).
 
 Contact KDAB at <[email protected]> to inquire about licensing options.
 
 Knut includes different 3rd party software, you can find the list and licenses for them in the [3RDPARTY](3RDPARTY.md) document.
 
-# Building
+## Building
 
 To build Knut, you will need an up-to-date C++ & Qt toolchain.
 This includes:
+
 - A recent C++ compiler (GCC 11+, Clang 15+, MSVC 19.40+)
 - [CMake](https://cmake.org) 3.15+
 - An installation of [Qt 6](https://www.qt.io/download-open-source)
 - (optional: [Ninja build system](https://ninja-build.org/))
 
-## Download Knut
+On Windows, you may run into issues when building, especially if using QtCreator.
+This is a known issue, and the steps to resolve it are detailed in the link to the Contributing Guide in the [Contributing](#contributing) section of this readme.
+
+### Download Knut
 
 To clone the code, simply run:
+
 ```bash
 git clone https://github.com/KDAB/knut.git && cd knut
 ```
 
 If you are a member of KDAB and have access to our private repositories, you may then simply run:
+
 ```bash
 git submodule update --init --recursive
 ```
-To download all dependencies.
+
+to download all dependencies.
 
 If you are a contributor outside KDAB, you will need to download all submodules in the `3rdparty/` folder, without the private dependencies in the `3rdparty-kdab/` folder.
+
 ```bash
 git submodule update --init --recursive -- 3rdparty/*
 ```
 
-## Running CMake
+### Running CMake
 
 After that you can build Knut with CMake via one of the presets.
 E.g.:
+
 ```bash
 cmake --preset=release
 cmake --build --preset=release
 ```
+
 Take a look at `CMakePreset.json` for a list of available presets.
 
-## Running Knut
+### Running Knut
 
 After building with CMake, run the knut binary from the bin folder within your build directory.
 
 e.g.:
+
 ```bash
 ./build-release/bin/knut
 ```
 
-# Documentation
+## Documentation
 
-Visit our comprehensive documentation here: https://kdab.github.io/knut/contributing/getting-involved.html
+Visit our comprehensive documentation here: [https://kdab.github.io/knut/index.html](https://kdab.github.io/knut/index.html)
 
-# Contributing
+## Contributing
 
-For information about contributing to Knut, see the ["Contributing guide"](https://kdab.github.io/knut/contributing/getting-involved.html) in our documentation.
+For information about contributing to Knut, see the ["Contributing Guide"](https://kdab.github.io/knut/contributing/getting-involved.html) in our documentation.
 
-# About KDAB
+## About KDAB
 
 Knut is written and maintained by Klarälvdalens Datakonsult AB (KDAB).
 
@@ -91,6 +102,6 @@ Please visit [https://www.kdab.com](https://www.kdab.com) to meet the people who
 
 Stay up-to-date with KDAB product announcements:
 
-* [KDAB Newsletter](https://news.kdab.com)
-* [KDAB Blogs](https://www.kdab.com/category/blogs)
-* [KDAB on Twitter](https://twitter.com/KDABQt)
+- [KDAB Newsletter](https://news.kdab.com)
+- [KDAB Blogs](https://www.kdab.com/category/blogs)
+- [KDAB on Twitter](https://twitter.com/KDABQt)

docs/contributing/getting-involved.md

@@ -26,22 +26,37 @@ Some useful ctest options include:
 - `--output-on-failure`
 
 When building with `--preset=debug-asan` you will likely want to disable leak checking:
+
 ```bash
 ASAN_OPTIONS=detect_leaks=0 ctest -j$(nproc) --preset=debug-asan --output-on-failure
 ```
 
 ### Qt Creator compilation error on Windows
 
-On Windows, if you use Qt Creator, you will have a compilation error like that:
+On Windows, if you use Qt Creator, you will have a compilation error like this:
 
-```
+```console
 [140/402 21.9/sec] Update documentation
 FAILED: CMakeFiles/docs C:/dev/knut/knut/build-debug/CMakeFiles/docs
 cmd.exe /C "cd /D C:\dev\knut\knut\build-debug && C:\dev\knut\knut\build-debug\bin\cpp2doc.exe"
 ```
 
+or a similar error with `ksyntaxhighlighting` or another 3rd party dependency.
+
 This is due to a bug in Qt Creator: [QTCREATORBUG-29936](https://bugreports.qt.io/browse/QTCREATORBUG-29963).
 
+To resolve this, follow these steps:
+
+1. Open `x64 Native Tools Command Prompt for VS 2022`.
+2. Enter the command `set CMAKE_PREFIX_PATH=C:\Qt\6.5.2\msvc2019_64` (use whatever path is correct on your machine).
+3. Enter the command `set PATH=C:\Qt\6.5.2\msvc2019_64\bin;%PATH%` (use whatever path is correct on your machine).
+4. Navigate to the `knut` directory with `cd`.
+5. Use cmake to configure and build:
+   - `"C:\Qt\Tools\CMake_64\bin\cmake.exe" --preset debug`
+   - `"C:\Qt\Tools\CMake_64\bin\cmake.exe" --build build-debug`
+6. You may need to run `windeployqt.exe` to make the knut executable link to Qt libraries properly:
+   - `windeployqt build-debug\bin\knut.exe`
+
 ## Code contributions
 
 In order to contribute code, make sure to read the following paragraphs.
@@ -50,7 +65,7 @@ In order to contribute code, make sure to read the following paragraphs.
 
 Make sure to install the pre-commit hooks. Those are installed using [`pre-commit`](https://pre-commit.com/):
 
-```
+```bash
 pip install pre-commit
 pre-commit install --hook-type commit-msg
 ```
@@ -94,7 +109,7 @@ For full documentation visit [mkdocs.org](https://www.mkdocs.org/).
 
 ### Installation
 
-```
+```bash
 pip install mkdocs
 pip install mkdocs-material
 pip install mkdocs-build-plantuml-plugin