From 9e99512e7646f447ec80cb0e3c460b5ae21f9af2 Mon Sep 17 00:00:00 2001
From: Leon Matthes <leon.matthes@kdab.com>
Date: Tue, 23 Jul 2024 16:55:58 +0200
Subject: [PATCH] chore(docs): Fix & Improve contribution docs

This commit fixes some broken links, updates the building & testing
documentation and adds a few badges.
---
 CMakePresets.json                     | 14 ++++++++++++++
 README.md                             | 12 ++++++++++++
 docs/contributing/architecture.md     |  2 +-
 docs/contributing/getting-involved.md | 25 +++++++++++++++++++------
 docs/contributing/unit-tests.md       |  2 +-
 docs/getting-started/treesitter.md    |  6 +++---
 6 files changed, 50 insertions(+), 11 deletions(-)

diff --git a/CMakePresets.json b/CMakePresets.json
index e56c527a..0b897869 100644
--- a/CMakePresets.json
+++ b/CMakePresets.json
@@ -104,6 +104,20 @@
             "name": "clazy",
             "inherits": "ci",
             "configurePreset": "clazy"
+        },
+        {
+            "name": "debug",
+            "inherits": "ci",
+            "configurePreset": "debug",
+            "execution": {
+                "noTestsAction": "error",
+                "stopOnFailure": false
+            }
+        },
+        {
+            "name": "debug-asan",
+            "inherits": "debug",
+            "configurePreset": "debug-asan"
         }
     ]
 }
diff --git a/README.md b/README.md
index 80ef339d..e13bba22 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
 # Knut
 
+[![GitHub branch status](https://img.shields.io/github/checks-status/KDAB/knut/main?logo=github)](https://github.com/KDAB/knut/actions)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSES/GPL-3.0-only.txt)
+[![MkDocs](https://img.shields.io/badge/MkDocs-526CFE?logo=materialformkdocs&logoColor=fff)](https://kdab.github.io/knut/)
+
 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.
@@ -67,6 +71,14 @@ e.g.:
 ./build-release/bin/knut
 ```
 
+# Documentation
+
+Visit our comprehensive documentation here: https://kdab.github.io/knut/contributing/getting-involved.html
+
+# Contributing
+
+For information about contributing to Knut, see the ["Contributing guide"](https://kdab.github.io/knut/contributing/getting-involved.html) in our documentation.
+
 # About KDAB
 
 Knut is written and maintained by Klarälvdalens Datakonsult AB (KDAB).
diff --git a/docs/contributing/architecture.md b/docs/contributing/architecture.md
index 67281c57..384f2a97 100644
--- a/docs/contributing/architecture.md
+++ b/docs/contributing/architecture.md
@@ -32,7 +32,7 @@ High-level architecture description.
 
 `KnutCore` is the central object in the application (module **core**), and is created in the `main.cpp`:
 
-- create the application singletons: [`Project`](../API/script/project.md), [`Settings`](../API/script/settings.md) and `ScriptManager`
+- create the application singletons: [`Project`](../API/knut/project.md), [`Settings`](../API/knut/settings.md) and `ScriptManager`
 - read parameters from the command line
 
 `KnutMain` is a subclass (module **gui**) that adds the gui specific parameters.
diff --git a/docs/contributing/getting-involved.md b/docs/contributing/getting-involved.md
index 1ebb2a31..3d2ecc5c 100644
--- a/docs/contributing/getting-involved.md
+++ b/docs/contributing/getting-involved.md
@@ -6,15 +6,28 @@ Please submit your contributions or issue reports from our GitHub space at <http
 
 ## Compilation
 
-To compile Knut, you need:
+For instructions on how to build and run Knut, refer to the [Building Section in the project README](https://github.com/kdab/knut?tab=readme-ov-file#building).
 
-- a C++20 compiler (recent compilers should work)
-- Qt 6.2 at least
+For development, you will likely want to use the `debug` or `debug-asan` CMake presets.
+Simply replace `--preset=release` with `--preset=debug` in the CMake calls.
 
-All 3rd-party dependencies are set up as git submodules, make sure to run:
+Note that if you're building with the `debug-asan`, asan will likely detect a few leaks from the larger dependencies like Qt, or even some drivers.
+This is mostly okay, and we haven't set up comprehensive suppressions, so they are expected.
 
-```
-git submodule update --init --recursive
+However, to avoid the tests failing, set the environment variable `ASAN_OPTIONS=detect_leaks=0` when running ctest.
+
+### Testing Knut
+
+To test Knut, use `ctest` or `ctest --preset=...` with the preset you used for building.
+
+Some useful ctest options include:
+
+- `-j$(nproc)` - runs multiple tests in parallel which can considerably speed up testing
+- `--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
diff --git a/docs/contributing/unit-tests.md b/docs/contributing/unit-tests.md
index f7e26d89..0eb122a3 100644
--- a/docs/contributing/unit-tests.md
+++ b/docs/contributing/unit-tests.md
@@ -1,6 +1,6 @@
 # Unit tests
 
-There are 2 different kinds of unit-tests: C++ and script. THey are located in the `tests` directory, with all test data in the `test_data` directory.
+There are 2 different kinds of unit-tests: C++ and script. They are located in the `tests` directory, with all test data in the `test_data` directory.
 
 ## C++ unit-tests
 
diff --git a/docs/getting-started/treesitter.md b/docs/getting-started/treesitter.md
index a6981827..fd583fec 100644
--- a/docs/getting-started/treesitter.md
+++ b/docs/getting-started/treesitter.md
@@ -222,6 +222,6 @@ Note that for most operations, using [`CppDocument::mfcExtractMessageMap`][extra
 [queries]: https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries
 [destructuring]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment?retiredLocale=de
 [template-literals]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals?retiredLocale=de
-[extract-message-map]: ../API/script/cppdocument.md#mfcExtractMessageMap
-[querymatch]: ../API/script/querymatch.md
-[codedocument-query]: ../API/script/codedocument.md#query
+[extract-message-map]: ../API/knut/cppdocument.md#mfcExtractMessageMap
+[querymatch]: ../API/knut/querymatch.md
+[codedocument-query]: ../API/knut/codedocument.md#query