backport: doc, tests, derivations & tool config

.github/workflows/cov.yml

@@ -3,7 +3,13 @@ name: Coverage
 on:
   push:
     branches: [ dev ]
-  pull_request:
+    paths:
+      - 'ai/**'
+      - 'server/**'
+      - 'gui/**'
+      - 'Makefile'
+      - 'tests/**'
+      - '.github/workflows/cov.yml'
 
 jobs:
   coverage:
@@ -16,22 +22,62 @@ jobs:
     - name: Install dependencies
       run: |
         sudo apt-get update
-        sudo apt-get install -y lcov gcovr make gcc
+        sudo apt-get install -y lcov gcovr make gcc g++ python3 python3-pip
+        pip install coverage pytest pytest-cov
 
-    - name: Build with coverage flags
+    - name: Clean build artifacts
+      run: make mrproper
+
+    # === Server (C) ===
+    - name: Build server with coverage flags
       run: |
-        make mrproper
         make tests_server
 
-    - name: Run tests
-      run: ./tests_server
+    - name: Run server tests
+      run: make tests_run_server
+
+    - name: Generate server coverage
+      run: |
+        gcovr --root . --filter 'server/' --xml-pretty -o coverage-server.xml --exclude 'tests/server/'
+
+    # === GUI (C++) ===
+    - name: Build GUI with coverage flags
+      run: make tests_gui
+
+    - name: Run GUI tests
+      run: make tests_run_gui
+
+    - name: Generate GUI coverage
+      run: |
+        gcovr --root . --filter 'GUI/' --xml-pretty -o coverage-gui.xml --exclude 'tests/gui/'
+
+    # === AI (Python) ===
+    - name: Run AI tests and generate coverage
+      run: |
+        make tests_run_ai
+        coverage xml -o ../coverage-ai.xml
+
+    # === Upload All Reports to Codecov ===
+    - name: Upload coverage to Codecov (server)
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: coverage-server.xml
+        flags: server
+        fail_ci_if_error: true
 
-    - name: Generate coverage report
-      run: gcovr --root . --xml-pretty -o coverage.xml
+    - name: Upload coverage to Codecov (GUI)
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: coverage-gui.xml
+        flags: gui
+        fail_ci_if_error: true
 
-    - name: Upload coverage to Codecov
+    - name: Upload coverage to Codecov (AI)
       uses: codecov/codecov-action@v4
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
-        files: coverage.xml
+        files: coverage-ai.xml
+        flags: ai
         fail_ci_if_error: true

.github/workflows/doc.yml

@@ -4,25 +4,24 @@ on:
   push:
     branches: [ dev ]
 
+permissions:
+  contents: write
+
 jobs:
   doc:
     runs-on: ubuntu-latest
 
     steps:
+    - name: Install Nix
+      uses: DeterminateSystems/nix-installer-action@v4
+
     - name: Checkout code
       uses: actions/checkout@v4
 
-    - name: Install dependencies
-      run: |
-        git submodule update --init
-        sudo apt-get install -y doxygen graphviz
-
-    - name: Build doc
-      run: doxygen Doxyfile
+    - name: Build documentation
+      run: nix build .#doc
 
-    - name: Upload doc to GitHub Pages
-      uses: peaceiris/actions-gh-pages@v3
+    - name: Upload GitHub Pages artifact
+      uses: actions/upload-pages-artifact@v3
       with:
-        force_orphan: true
-        deploy_key: ${{ secrets.GH_SSH_PRIVATE_KEY }}
-        publish_dir: ./.doc/html
+        path: ./result

.gitignore

@@ -22,6 +22,7 @@ __pycache__
 *.[aod]
 *.so
 *.egg-info
+.coverage
 
 # Editors
 .idea
@@ -34,3 +35,6 @@ a.out
 
 # Documentation
 .doc
+docs/build
+docs/doxygen
+docs/source/api

Doxyfile

@@ -1,68 +1,26 @@
-#-------------------- Project Information --------------------
-PROJECT_NAME           = "ZAPPY"
-PROJECT_BRIEF          = "A Tribute to Zaphod Beeblebrox"
-OUTPUT_DIRECTORY       = .doc
+PROJECT_NAME = Zappy
+INPUT = server gui
 
-#-------------------- Input --------------------
-INPUT                  = server/ gui/ ai/ README.md
-FILE_PATTERNS          = *.c *.cpp *.h *.hpp *.py
-RECURSIVE              = YES
-USE_MDFILE_AS_MAINPAGE = README.md
+FILE_PATTERNS = *.c *.cpp *.h *.hpp
+RECURSIVE = YES
 
-#-------------------- Build Options --------------------
-CREATE_SUBDIRS         = YES
-CREATE_SUBDIRS_LEVEL   = 8
-MARKDOWN_SUPPORT       = YES
-MARKDOWN_ID_STYLE      = DOXYGEN
-TOC_INCLUDE_HEADINGS   = 5
-INPUT_ENCODING         = UTF-8
-PYTHON_DOCSTRING       = YES
-EXTRACT_LOCAL_CLASSES  = YES
-SHOW_NAMESPACES        = YES
-SOURCE_BROWSER         = YES
-INLINE_SOURCES         = YES
-STRIP_CODE_COMMENTS    = YES
-REFERENCES_LINK_SOURCE = YES
-SOURCE_TOOLTIPS        = YES
-WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
-WARN_IF_DOC_ERROR      = YES
-WARN_IF_INCOMPLETE_DOC = YES
-GENERATE_TODOLIST      = YES
-GENERATE_TESTLIST      = YES
-GENERATE_BUGLIST       = YES
-GENERATE_DEPRECATEDLIST= YES
-SHOW_FILES             = NO
-SHOW_HEADERFILE        = NO
-SHOW_INCLUDE_FILES     = NO
-SHOW_USED_FILES        = NO
+OUTPUT_DIRECTORY = .build/doxygen
 
-#-------------------- HTML Output --------------------
-GENERATE_HTML          = YES
-HTML_OUTPUT            = html
-HTML_EXTRA_STYLESHEET  = doxygen-awesome-css/doxygen-awesome.css              \
-                         doxygen-awesome-css/doxygen-awesome-sidebar-only.css
-HTML_COLORSTYLE        = AUTO_LIGHT
-HTML_DYNAMIC_MENUS     = YES
-HTML_CODE_FOLDING      = YES
-GENERATE_TREEVIEW      = YES
+GENERATE_LATEX = NO
+GENERATE_XML = YES
+XML_OUTPUT = xml
 
-#-------------------- Graphs --------------------
-HAVE_DOT               = YES
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = YES
-GROUP_GRAPHS           = YES
-INCLUDE_GRAPH          = YES
-INCLUDED_BY_GRAPH      = YES
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH        = YES
-DOT_IMAGE_FORMAT       = svg
-DOT_PATH               = /usr/bin/env
+HAVE_DOT = yes  # enables graphviz diagrams in Doxygen
+DOT_PATH = dot
 
-#-------------------- Miscellaneous --------------------
-OBFUSCATE_EMAILS       = YES
+EXTRACT_ALL = YES
+EXTRACT_STATIC = YES
+EXTRACT_LOCAL_CLASSES = YES
+EXTRACT_PRIVATE = YES
+EXTRACT_ANON_NSPACES = YES
 
-#-------------------- Exclude/Filter (if needed) --------------------
-FILTER_SOURCE_FILES    = YES
+ALIASES = "todo=TODO" "bug=BUG" "warning=WARNING"
 
-#-------------------- End of file --------------------
+EXCLUDE_SYMBOLS = main
+BUILTIN_STL_SUPPORT = YES
+PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS

Doxygen.vim

@@ -0,0 +1,30 @@
+if expand('%:f') !=# 'Doxyfile'
+  finish
+endif
+
+" Comments
+syntax match doxyComment "#.*$"
+highlight link doxyComment Comment
+
+" Keys (must come first, but match only the key part)
+syntax match doxyKey "^\s*\zs[A-Z_]\+\ze\s*\(+=\|=\)"
+highlight link doxyKey Keyword
+
+" Operators
+syntax match doxyOperator "\(+=\|=\)"
+highlight link doxyOperator Operator
+
+" Booleans
+syntax match doxyBool "\<\(YES\|NO\)\>"
+highlight link doxyBool Constant
+
+" Strings in quotes
+syntax region doxyString start=/"/ skip=/\\"/ end=/"/ keepend
+highlight link doxyString String
+
+" Patterns like *.c or *.h
+syntax match doxyPattern "\*\.[ch]\(pp\)\?"
+highlight link doxyPattern Type
+
+let b:current_syntax = "doxygenconf"
+

Makefile

@@ -7,6 +7,8 @@ LD := $(CC)
 AR ?= ar
 RM ?= rm --force
 
+CFLAGS := -std=c2x
+
 CXXFLAGS := -std=c++20
 CXXFLAGS += -iquote $/libs -iquote $/include
 
@@ -22,6 +24,8 @@ CXXFLAGS_debug := -g3 -fsanitize=address,leak,undefined -DDEBUG_MODE=1
 
 CFLAGS_cov := --coverage -g3
 CXXFLAGS_cov := --coverage -g3
+CFLAGS_tests := --coverage -g3
+CXXFLAGS_tests := --coverage -g3
 
 LDLIBS :=
 LDFLAGS :=
@@ -39,11 +43,15 @@ GENERIC_FLAGS_CPP := CXX
 
 NAME_server_release := zappy_server
 NAME_server_debug := debug_server
-NAME_server_cov := tests_server
+NAME_server_tests := tests_server
 
 NAME_gui_release := zappy_gui
 NAME_gui_debug := debug_gui
-NAME_gui_cov := tests_gui
+NAME_gui_tests := tests_gui
+
+EXTRA_SRC_gui_tests != find tests/gui -name "*.cpp"
+
+EXTRA_SRC_server_tests != find tests/server -type f -name "*.c"
 
 # call mk-bin, bin-name, profile, lang
 # DOES THIS MAKE COFFEE NOW ??
@@ -61,7 +69,8 @@ $(BUILD)/$(strip $2)/%.o: %.$(GENERIC_SUFFIX_$(strip $3))
 
 out_$(strip $1)_$(strip $2) := $(NAME_$(strip $1)_$(strip $2))
 src_$(strip $1)_$(strip $2) !=                                                \
-	find $(strip $1) -type f -name "*.$(GENERIC_SUFFIX_$(strip $3))"
+    find $(strip $1) -type f -name "*.$(GENERIC_SUFFIX_$(strip $3))"
+src_$(strip $1)_$(strip $2) += $(EXTRA_SRC_$(strip $1)_$(strip $2))
 
 objs_$(strip $1)_$(strip $2) :=                                               \
 	$$(src_$(strip $1)_$(strip $2):%.$(GENERIC_SUFFIX_$(strip                 \
@@ -84,15 +93,14 @@ LANG_server := C
 LANG_gui := CPP
 
 $(foreach target, server gui,                                                 \
-$(foreach build-mode, release debug cov,                                      \
-	$(eval $(call generic-o-builder, $(build-mode), $(LANG_$(target))))       \
+$(foreach build-mode, release debug tests,                                    \
 	$(eval $(call mk-bin, $(target), $(build-mode), $(LANG_$(target))))       \
 ))
 
 ifeq ($(V),2)
 $(foreach target, server gui,                                                 \
-$(foreach build-mode, release debug cov,                                      \
-	$(eval $(call mk-bin, $(target), $(build-mode), $(LANG_$(target))))       \
+$(foreach build-mode, release debug cov tests,                                \
+	$(info $(call mk-bin, $(target), $(build-mode), $(LANG_$(target))))       \
 ))
 endif
 
@@ -102,13 +110,16 @@ all: zappy_server zappy_gui zappy_ai
 
 ifneq ($(auto-complete),)
 # auto complete for dumb terminals
+
 debug_gui:
 debug_server:
 zappy_ai:
 zappy_gui:
 zappy_server:
 tests_gui:
 tests_server:
+tests_run_server:
+tests_run_gui:
 endif
 
 venv:
@@ -122,6 +133,11 @@ zappy_ai: venv $(shell find ai -type f -name "*.py")
 	$Q cp venv/bin/zappy_ai $@
 	@ $(LOG_TIME) "CP $(C_GREEN)$@ $(C_RESET)"
 
+html-doc: #? html-doc: Build the static html documentation
+	doxygen Doxyfile
+	$(MAKE) -C docs html
+	@ $(LOG_TIME) "DO $(C_YELLOW)$@ $(C_RESET)"
+
 .PHONY: help
 help: #? help: Show this help message
 	@ grep -P "#[?] " $(MAKEFILE_LIST)                                        \
@@ -136,11 +152,34 @@ fclean: clean
 	$(RM) $(every_out) zappy_ai
 
 mrproper: fclean
-	$(RM) -rf .build compile_commands.json
+	$(RM) -rf venv $(BUILD)
+	$(RM) -rf $(BUILD)
+	$(RM) -rf docs/source/api docs/doxygen
+	$(RM) -rf compile_commands.json
 
 .NOTPARALLEL: re
 re: fclean all
 
+tests_run_%: tests_%
+	./$^
+
+tests_run_ai: venv
+	pytest . --cov=ai --no-summary
+
+.PHONY: cov cov_ai cov_server cov_gui
+
+cov_ai: tests_run_ai
+	coverage report -m
+
+cov_gui: tests_run_gui
+	gcovr $(BUILD)/tests/gui --exclude=tests
+
+cov_server: tests_run_server
+	gcovr $(BUILD)/tests/server --exclude=tests
+
+.NOTPARALLEL: cov
+cov: cov_ai cov_gui cov_server
+
 V ?= 0
 ifneq ($(V),0)
   Q :=