[DOC] add explanations + change title styling

Author: SimonBlanke

docs/source/_static/css/custom.css

@@ -132,6 +132,17 @@ html[data-theme="dark"] {
     margin-top: 1.25rem;
 }
 
+/* Remove vertical line from right sidebar */
+.bd-sidebar-secondary .toc-entry,
+.bd-sidebar-secondary nav.page-toc {
+    border-left: none;
+}
+
+/* Fixed position for right sidebar */
+.bd-sidebar-secondary {
+    min-width: 200px;
+}
+
 .pst-page-navigation-heading {
     margin-bottom: 0.5rem;
 }
@@ -930,14 +941,43 @@ hr {
 }
 
 /* ============================================
-   Section Headers - Clean without decorative underlines
+   Section Headers - Subtle styling
    ============================================ */
-h2 {
+
+/* Page titles (h1 from ===) - subtle background highlight */
+/* Exclude home page by targeting pages with h1 that aren't in the hero */
+article h1:not(.hero-title) {
+    background-color: rgba(93, 93, 122, 0.2);
+    padding: 0.5rem 0.75rem;
+    border-radius: 4px;
+    width: fit-content;
+}
+
+/* Home page h1s get h2 styling (underline, not background) */
+/* Target pages that contain .hero-section */
+article:has(.hero-section) h1 {
+    background-color: transparent;
+    padding: 0;
+    border-radius: 0;
+    width: auto;
+    padding-bottom: 0.4rem;
+    border-bottom: 1px solid var(--pst-color-border);
+}
+
+/* Remove headerlink from affecting h1 width */
+article h1 a.headerlink {
+    position: absolute;
+    margin-left: 0.5rem;
+}
+
+/* Section titles (h2 from ---) - subtle underline */
+article h2 {
     position: relative;
-    padding-bottom: 0;
+    padding-bottom: 0.4rem;
+    border-bottom: 1px solid var(--pst-color-border);
 }
 
-/* Remove the short underline pseudo-element */
+/* Remove any pseudo-element underlines */
 h2::after {
     display: none;
 }

docs/source/index.rst

@@ -60,7 +60,7 @@ alongside direct interfaces to Optuna and scikit-learn optimizers.
 .. _features:
 
 Features
-================
+========
 
 What makes Hyperactive stand out for optimization tasks.
 
@@ -136,7 +136,7 @@ What makes Hyperactive stand out for optimization tasks.
 ----
 
 Optimization Backends
-==================
+=====================
 
 Hyperactive provides a unified interface to three powerful optimization backends.
 Choose the one that best fits your needs, or switch between them effortlessly.

docs/source/user_guide/experiments.rst

@@ -4,7 +4,10 @@
 Experiments
 ===========
 
-Define what to optimize.
+An experiment is the objective function that evaluates parameters and returns a score.
+It encapsulates your optimization problem separately from the optimizer, so you can
+swap algorithms without changing your evaluation code. Hyperactive supports custom
+functions and built-in classes for common ML tasks with cross-validation.
 
 ----
 

docs/source/user_guide/integrations.rst

@@ -4,9 +4,10 @@
 Framework Integrations
 ======================
 
-Use Hyperactive with your favorite ML frameworks. These integrations provide
-drop-in replacements for tools like ``GridSearchCV``, letting you use any
-Hyperactive optimizer with minimal code changes.
+Hyperactive integrates with popular ML frameworks, providing drop-in replacements
+for tools like ``GridSearchCV``. Each ML framework has its own conventions for training and evaluation. The integration
+classes handle cross-validation setup, scoring metrics, and parameter translation, so
+you can use any optimizer with scikit-learn, sktime, skpro, or PyTorch models.
 
 ----
 

docs/source/user_guide/introduction.rst

@@ -4,7 +4,10 @@
 Introduction
 ============
 
-Learn the fundamentals of Hyperactive and start optimizing in minutes.
+Optimization finds the best parameters from a set of possibilities. Evaluating every
+combination is usually impractical, so algorithms guide the search. Hyperactive provides
+a unified interface: define your problem once, then swap between different optimization
+algorithms without changing your code.
 
 ----
 

docs/source/user_guide/optimizers/index.rst

@@ -4,8 +4,12 @@
 Optimizers
 ==========
 
-Choose the right algorithm for your optimization problem.
 Hyperactive provides 31 algorithms across 5 categories and 3 backends.
+Optimizers navigate the search space to find optimal parameters. Each implements a
+different strategy for balancing exploration (trying diverse regions) and exploitation
+(refining promising solutions). Local search methods like Hill Climbing work well for
+smooth landscapes. Population-based methods handle multiple local optima. Model-based
+methods like Bayesian Optimization minimize evaluations for expensive objective functions.
 
 ----
 

docs/source/user_guide/search_spaces.rst

@@ -4,7 +4,9 @@
 Search Spaces
 =============
 
-Define where to search for optimal parameters.
+The search space defines all configurations the optimizer can explore. Too narrow and
+you miss good solutions; too broad and the optimizer wastes iterations. In Hyperactive,
+search spaces are dictionaries mapping parameter names to lists of possible values.
 
 ----