YT-CPPGL-61: Prepare the GL module's documentation

.gitignore

@@ -9,9 +9,14 @@
 
 # documentation files
 documentation/
+site/
+mike-*.yml
+docs/cpp-gl/
 
 # python temporary files
 **/__pycache__/
+.ruff_cache/
+.venv/
 
 # other
 *tmp*/

.python-version

@@ -0,0 +1 @@
+3.14

LICENSE → LICENSE.md

@@ -1,8 +1,8 @@
-MIT License
+#### MIT License
 
-Copyright (c) 2024 Jakub Musiał
-Project: "CPP-GL: General purpose header-only template graph library for C++23 and newer standards."
-https://github.com/SpectraL519/cpp-gl
+Copyright (c) 2024-2026 Jakub Musiał  
+Project: "CPP-GL: General-purpose Template Graph and Hypergraph Library for Modern C++"  
+URL: https://github.com/SpectraL519/cpp-gl
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -0,0 +1,24 @@
+# Default to 'dev' if TAGS is not specified on the command line
+TAGS ?= dev
+
+.PHONY: docs serve-docs clean-docs clean
+
+# Example usage: `make docs TAGS="v2.0.0 latest --update-aliases"`
+docs: clean-docs
+	@echo "==> Deploying MkDocs documentation locally via mike (Tags: $(TAGS))..."
+	doxygen Doxyfile
+	uv run python docs/scripts/gen_concept_docs.py --config docs/config/concepts.json --xml documentation/xml --out docs/cpp-gl
+	uv run mike deploy $(TAGS)
+	@echo "==> Documentation deployed to local gh-pages branch."
+
+serve-docs: docs
+	@echo "==> Serving versioned MkDocs documentation locally via mike..."
+	uv run mike serve
+
+clean-docs:
+	@echo "==> Cleaning documentation build directories..."
+	rm -rf docs/cpp-gl/
+	rm -rf site/
+	rm -rf documentation/
+
+clean: clean-docs

README.md

@@ -8,10 +8,10 @@
 
 <div align="center">
 
-[![g++](https://github.com/SpectraL519/cpp-gl/actions/workflows/gpp.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/g++)
-[![clang++](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang++)
-[![format](https://github.com/SpectraL519/cpp-gl/actions/workflows/format.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/format)
-[![benchmarks](https://github.com/SpectraL519/cpp-gl/actions/workflows/benchmarks.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/benchmarks.yaml)
+[![G++](https://github.com/SpectraL519/cpp-gl/actions/workflows/gpp.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/gpp.yaml)
+[![Clang++](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang.yaml)
+[![Code Formatting](https://github.com/SpectraL519/cpp-gl/actions/workflows/format.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/format.yaml)
+[![Benchmarks Smoke Test](https://github.com/SpectraL519/cpp-gl/actions/workflows/benchmarks.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/benchmarks.yaml)
 
 </div>
 
@@ -108,4 +108,4 @@ target_link_libraries(my_project PRIVATE cpp-gl)
 
 ## Licence
 
-The `CPP-GL` project uses the [MIT Licence](https://mit-license.org/) which can be found in the [LICENCE](/LICENSE) file
+The `CPP-GL` project uses the [MIT Licence](https://mit-license.org/) which can be found in the [LICENCE](/LICENSE.md#mit-licence) file

docs/config/concepts.json

@@ -0,0 +1,23 @@
+{
+    "index": {
+        "title": "Concepts API Reference",
+        "anchor": "concepts-api-reference",
+        "description": "This page serves as the central index for all C++20 concepts defined within the library."
+    },
+    "groups": {
+        "GL": {
+            "prefix": "gl::",
+            "filename": "gl_concepts.md",
+            "anchor": "gl-concepts-documentation",
+            "title": "GL Concepts",
+            "description": "This page documents the C++20 concepts defined within the GL module of the library."
+        },
+        "HGL": {
+            "prefix": "hgl::",
+            "filename": "hgl_concepts.md",
+            "anchor": "hgl-concepts-documentation",
+            "title": "HGL Concepts",
+            "description": "This page documents the C++20 concepts defined within the HGL module of the library."
+        }
+    }
+}

docs/config/groups.dox

@@ -0,0 +1,85 @@
+/// @defgroup GL Graph Library (GL)
+/// @brief The top-level module defining the general-purpose C++ template graph library.
+///
+/// This module provides a comprehensive suite of memory-efficient graph representations,
+/// highly customizable algorithms, topology generators, and robust I/O facilities. Designed
+/// strictly around modern C++ paradigms, the library heavily leverages templates and concepts
+/// to deliver an API that is exceptionally fast, generic, and type-safe.
+
+/// @defgroup GL-Core Core Graph Components
+/// @ingroup GL
+/// @brief Fundamental graph data structures, element descriptors, and configuration tags.
+///
+/// This group establishes the primary user interface for the library, centered around the highly
+/// configurable @ref gl::graph "graph" class. It provides the core data types, such as vertex
+/// and edge descriptors, required to safely navigate and manipulate graph elements.
+///
+/// Furthermore, this module defines the declarative tags (e.g., directedness and backend
+/// implementation types) that dictate both the behavioral semantics and the underlying memory
+/// layout of the instantiated graphs.
+
+/// @defgroup GL-Algorithm Graph Algorithms
+/// @ingroup GL
+/// @brief Generic graph algorithms, foundational search templates, and related utilities.
+///
+/// This module provides a dual-layered approach to graph algorithms. At its core, it features highly
+/// generic and extensible search templates (such as BFS, DFS, and Priority-First Search). These
+/// templates serve as the foundational building blocks of the library, empowering users to inject
+/// custom behavior via callbacks and predicates to build entirely new algorithms with minimal effort.
+///
+/// Alongside these templates, the module offers a suite of concrete, ready-to-use algorithms.
+/// Rather than a flat list of functions, the algorithms are categorized into broad domains,
+/// including basic graph traversal, pathfinding, minimum spanning trees, and topological
+/// operations like sorting and coloring. All implementations are designed to operate seamlessly
+/// with generic graph types and property maps.
+
+/// @defgroup GL-Topology Graph Topologies
+/// @ingroup GL
+/// @brief Generators and evaluators for standard structural graph topologies.
+///
+/// A collection of lightweight utilities designed to quickly instantiate classic graph topologies.
+/// Featuring out-of-the-box support for cliques (complete graphs), bipartite graphs, binary trees,
+/// paths, and cycles, these generators are ideal for rapid prototyping, algorithm benchmarking,
+/// and automated testing.
+
+/// @defgroup GL-IO I/O Utility
+/// @ingroup GL
+/// @brief Comprehensive I/O stream support, parsing algorithms, and range-based formatting.
+///
+/// This group provides the necessary infrastructure to seamlessly serialize, deserialize, and
+/// visualize complex graph structures. By offering a robust set of stream manipulators, formatting
+/// traits, and configuration options, it allows users to easily translate in-memory graphs to
+/// and from standard streams, files, or custom string representations.
+
+/// @defgroup GL-Traits Traits & Concepts
+/// @ingroup GL
+/// @brief Type traits, template constraints, and compile-time metaprogramming utilities.
+///
+/// Encapsulating the `gl::traits` namespace, these components form the strict conceptual backbone
+/// of the library. They are used extensively to constrain template parameters, safely query type
+/// properties at compile time, and ensure that user-provided graphs and property maps meet
+/// required structural and behavioral contracts.
+///
+/// @section concepts_link Detailed Concept Specifications
+/// For a detailed list of all GL module's concepts and their formal requirements, please refer to
+/// the [GL Concepts Documentation](gl_concepts.md#gl-concepts-documentation) page.
+
+/// @defgroup GL-Types Generic Types
+/// @ingroup GL
+/// @brief Independent, high-performance data structures and utility types.
+///
+/// This module houses a variety of general-purpose data structures and types. While it features
+/// highly optimized memory containers (such as @ref gl::flat_matrix "flat_matrix" and
+/// @ref gl::flat_jagged_vector "flat_jagged_vector") that serve as the contiguous-memory backbones
+/// for the library's graphs, it also encompasses other fundamental type utilities. Because all
+/// components in this group are carefully decoupled from graph-specific logic, they can be seamlessly
+/// extracted and utilized in broader C++ programming contexts.
+
+/// @defgroup GL-Util General Utilities
+/// @ingroup GL
+/// @brief Practical, domain-agnostic C++ helpers, mathematical functions, and polyfills.
+///
+/// While originally engineered to support the library's internal algorithms and graph modeling
+/// operations, these utilities are completely independent of graph theory semantics. They provide
+/// a curated set of highly reusable, general-purpose tools that can smoothly integrate into any
+/// modern C++ codebase.

docs/gl/advanced.md

@@ -0,0 +1,42 @@
+# Advanced Features
+
+The CPP-GL library is designed to be highly configurable, allowing developers to tune the library's internal behavior to meet strict performance and architectural requirements.
+
+This page outlines the advanced configuration toggles and features available in the library.
+
+---
+
+## Forced Function Inlining
+
+By default, C++ compilers use their own internal heuristics to decide whether a function marked with the `inline` keyword should actually be inlined. While modern compilers are generally excellent at this, relying purely on default cost models can sometimes leave small, heavily utilized accessors or structural traversal utilities un-inlined.
+
+To guarantee zero-overhead abstraction in the most performance-critical code paths, CPP-GL provides an opt-in macro to forcibly inline a carefully selected set of core library methods.
+
+### Enabling Forced Inlining
+
+You can enable this feature by defining the `GL_CONFIG_FORCE_INLINE` macro. For consistent behavior across translation units, it is highly recommended to define this globally through your build system rather than in individual source files.
+
+**Via CMake (Recommended):**
+
+```cmake
+target_compile_definitions(my_application PRIVATE GL_CONFIG_FORCE_INLINE)
+```
+
+**Via Code:**
+
+If you must define it in code, ensure it is defined before including any CPP-GL headers.
+
+```cpp
+#define GL_CONFIG_FORCE_INLINE
+#include <gl/graph.hpp>
+```
+
+### How it Works
+
+When `GL_CONFIG_FORCE_INLINE` is active, the library applies compiler-specific attributes, such as `[[clang::always_inline]]` for Clang or `[[gnu::always_inline]]` for GCC, to critical internal functions. This bypasses the compiler's standard inlining heuristics. If the macro is left undefined, the library safely falls back to using the standard C++ inline keyword.
+
+> [!WARNING] Performance Trade-offs
+>
+> Forcing the compiler to inline functions is a double-edged sword. While it eliminates function call overhead and can expose more optimization opportunities (like constant propagation), it can also lead to significant code bloat.
+>
+> Excessively large binaries can cause instruction cache (i-cache) misses, which may ultimately degrade performance rather than improve it. Always profile and benchmark your application with and without `GL_CONFIG_FORCE_INLINE` to ensure it provides a tangible benefit for your specific workload.

docs/gl/algorithms/overview.md

@@ -0,0 +1,74 @@
+# Algorithms Overview
+
+The CPP-GL algorithms module is designed with a strict architectural separation of concerns. Rather than writing monolithic functions that handle both search mechanics and specific problem-solving logic, the library splits graph processing into two distinct layers: **Generic Templates (Engines)** and **Concrete Algorithms**.
+
+This separation ensures maximum code reuse, provides strict zero-cost abstractions, and allows power users to inject highly customized logic directly into the traversal control flow.
+
+## The Architectural Separation
+
+### 1. The Generic Templates (Engines)
+
+Located at the lowest level, the generic templates define the strict structural execution of a search. They know nothing about *shortest paths*, *spanning trees*, or *cycle detection*. Their only responsibility is to manage the pending elements (a queue, stack, or priority queue) and invoke a series of user-provided callback hooks at specific moments during the traversal.
+
+The core generic templates include:
+
+- [**`bfs`**](templates.md#the-core-engines): A queue-based Breadth-First Search engine.
+- [**`dfs`**](templates.md#the-core-engines): A stack-based, iterative Depth-First Search engine.
+- [**`r_dfs`**](templates.md#the-core-engines): A recursive Depth-First Search engine utilizing the call stack.
+- [**`pfs`**](templates.md#the-core-engines): A priority-queue-based Priority-First Search engine for custom heuristics.
+
+### 2. The Concrete Algorithms
+
+Concrete algorithms (like `dijkstra_shortest_paths`, `topological_sort`, or `breadth_first_search`) are essentially lightweight wrappers around the generic engines. They are responsible for:
+- Allocating and managing memory for algorithm state tracking (e.g., `std::vector<bool> visited` arrays, distance maps).
+- Defining the specific logic inside the lambda callbacks and predicates.
+- Managing the final return types and structures.
+
+By separating these layers, CPP-GL guarantees that all algorithms inherently benefit from the exact same optimized design and element management.
+
+## Core Algorithm Elements
+
+To interact with the generic templates or understand the concrete algorithms, you must be familiar with a few foundational types and tags used uniformly across the library.
+
+### Zero-Cost Callbacks
+
+The generic engines accept up to 5 or 6 different callbacks per invocation. However, forcing the compiler to execute or optimize away empty lambdas (e.g., `[]{}`) can add overhead in debug builds and slow down compilation.
+
+To solve this, CPP-GL uses the [**gl::algorithm::empty_callback**](../../cpp-gl/structgl_1_1algorithm_1_1empty__callback.md) tag. If a hook is not needed, the engine receives this tag, and compile-time evaluation (`if constexpr`) completely optimizes away that branch of execution.
+
+### Tri-State Control Flow
+
+When evaluating adjacent edges during a search, algorithms often need more control than a simple `true`/`false`. The [**gl::algorithm::decision**](../../cpp-gl/structgl_1_1algorithm_1_1decision.md) struct provides a tri-state evaluation:
+
+- `decision::accept`: Proceed with the element (e.g., push it to the queue).
+- `decision::reject`: Skip this specific element, but continue the search.
+- `decision::abort`: Instantly terminate the entire algorithm.
+
+For convenience, `decision` implicitly constructs from a boolean, where `true` maps to `accept` and `false` maps to `reject`. Furthermore, `decision` provides a boolean conversion operator, allowing it to be seamlessly evaluated in standard conditional statements (`if (enqueue_decision) { ... }`).
+
+### The Search Node
+
+By default, the active container of a search engine stores [**gl::algorithm::search_node<G>**](../../cpp-gl/structgl_1_1algorithm_1_1search__node.md) structures. This is a lightweight pair containing:
+
+1. `vertex_id`: The vertex currently being visited.
+2. `pred_id`: The vertex from which this current vertex was reached (its parent in the traversal tree).
+
+If a vertex is the starting point of a search, its `pred_id` is set to itself, making it a "root" node. The library provides the [**gl::algorithm::no_root**](../../cpp-gl/group__GL-Algorithm.md#variable-no_root) tag to explicitly identify states where a node lacks a predecessor.
+
+### The Result Discriminator
+
+Certain algorithms can either return a fully constructed result (like a tree mapping every vertex to its predecessor) or run purely for side-effects (like executing a lambda on every visited node).
+
+CPP-GL manages this via the [**gl::algorithm::result_discriminator**](../../cpp-gl/group__GL-Algorithm.md#enum-result_discriminator) enum.
+- `ret`: The algorithm will allocate memory and return a stateful object (e.g., `predecessors_map<G>`).
+- `noret`: The algorithm will execute purely for side-effects and return `void` (or a simple success boolean).
+
+## Available Concrete Algorithms
+
+Explore the specific layers of the algorithm module below:
+
+- [**The Generic Templates**](templates.md): A detailed explanation of the core traversal engines and their execution sequence.
+- [**Concrete Traversals**](traversal.md): Standard wrappers for basic component discovery and state-tracked searching.
+- [**Pathfinding**](pathfinding.md): Algorithms for finding the shortest path between nodes (e.g., Dijkstra).
+- [**Spanning Trees**](spanning_trees.md): Algorithms for finding Minimum Spanning Trees (e.g., Prim's).
+- [**Topological Algorithms**](topological_algs.md): Structural algorithms like topological sorting and bipartite coloring.