Skip to content

Commit 4ec28a1

Browse files
SimonBlankeSimonBlanke
committed
rework the entire docs
1 parent c17c1be commit 4ec28a1

File tree

106 files changed

+1882
-168
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

106 files changed

+1882
-168
lines changed

‎docs/source/_static/css/custom.css‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1075,3 +1075,101 @@ html[data-theme="dark"] .segmented-tab-btn.active {
10751075
html[data-theme="dark"] .theme-aware-diagram img.only-dark {
10761076
background-color: transparent !important;
10771077
}
1078+
1079+
/* ============================================
1080+
Left Sidebar Navigation - Improved UX
1081+
============================================ */
1082+
1083+
/* Hide all expand/collapse arrow icons */
1084+
.bd-sidebar-primary .toctree-toggle,
1085+
.bd-sidebar-primary button.toctree-toggle,
1086+
.bd-sidebar-primary .nav-link .icon-tabler,
1087+
.bd-sidebar-primary .toc-item-toggle,
1088+
.bd-sidebar-primary i.fa-chevron-down,
1089+
.bd-sidebar-primary i.fa-chevron-right,
1090+
.bd-sidebar-primary .toggle-chevron,
1091+
.bd-sidebar-primary label.toctree-toggle {
1092+
display: none !important;
1093+
}
1094+
1095+
/* Make entire nav item row clickable by ensuring link fills container */
1096+
.bd-sidebar-primary .nav-item {
1097+
position: relative;
1098+
}
1099+
1100+
.bd-sidebar-primary .nav-link {
1101+
display: block;
1102+
width: 100%;
1103+
cursor: pointer;
1104+
}
1105+
1106+
/* Levels 1 and 2 are expanded by JavaScript on page load */
1107+
1108+
/* Visual indicator for expandable items - pointer cursor on link */
1109+
.bd-sidebar-primary li.has-children > a {
1110+
cursor: pointer;
1111+
}
1112+
1113+
/* Improve click target size */
1114+
.bd-sidebar-primary .nav-link {
1115+
padding: 0.375rem 0.75rem;
1116+
margin: 1px 0;
1117+
border-radius: 4px;
1118+
transition: background-color 0.15s ease;
1119+
}
1120+
1121+
/* Hover state for better feedback */
1122+
.bd-sidebar-primary .nav-link:hover {
1123+
background-color: var(--pst-color-background);
1124+
}
1125+
1126+
/* Active item styling - subtle left border accent, no background */
1127+
.bd-sidebar-primary .nav-link.active,
1128+
.bd-sidebar-primary .current > .nav-link,
1129+
.bd-sidebar-primary .current > a {
1130+
color: var(--surfaces-primary);
1131+
border-left: 2px solid var(--surfaces-primary);
1132+
padding-left: calc(0.75rem - 2px);
1133+
}
1134+
1135+
html[data-theme="dark"] .bd-sidebar-primary .nav-link.active,
1136+
html[data-theme="dark"] .bd-sidebar-primary .current > .nav-link,
1137+
html[data-theme="dark"] .bd-sidebar-primary .current > a {
1138+
color: var(--surfaces-secondary);
1139+
border-left-color: var(--surfaces-secondary);
1140+
}
1141+
1142+
/* Remove default list styling artifacts */
1143+
.bd-sidebar-primary ul {
1144+
list-style: none;
1145+
padding-left: 0;
1146+
margin: 0;
1147+
}
1148+
1149+
/* Indent nested levels */
1150+
.bd-sidebar-primary .toctree-l2 {
1151+
padding-left: 0.75rem;
1152+
}
1153+
1154+
.bd-sidebar-primary .toctree-l3 {
1155+
padding-left: 1.5rem;
1156+
}
1157+
1158+
.bd-sidebar-primary .toctree-l4 {
1159+
padding-left: 2.25rem;
1160+
}
1161+
1162+
/* Consistent font size/weight across all levels - only color varies */
1163+
.bd-sidebar-primary .toctree-l1 > a,
1164+
.bd-sidebar-primary .toctree-l2 > a,
1165+
.bd-sidebar-primary .toctree-l3 > a,
1166+
.bd-sidebar-primary .toctree-l4 > a {
1167+
font-weight: 400;
1168+
font-size: 0.85rem;
1169+
}
1170+
1171+
/* Subtle color difference for deeper levels */
1172+
.bd-sidebar-primary .toctree-l3 > a,
1173+
.bd-sidebar-primary .toctree-l4 > a {
1174+
color: var(--pst-color-text-muted);
1175+
}

‎docs/source/_static/js/sidebar-toggle.js‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
/**
2+
* Sidebar Navigation Toggle
3+
*
4+
* Makes entire navigation rows clickable to expand/collapse their children.
5+
* Works with pydata-sphinx-theme's <details>/<summary> structure.
6+
*/
7+
document.addEventListener('DOMContentLoaded', function() {
8+
const sidebar = document.querySelector('.bd-sidebar-primary');
9+
if (!sidebar) return;
10+
11+
// Find all nav items that have a details element (expandable)
12+
const expandableItems = sidebar.querySelectorAll('li.has-children');
13+
14+
expandableItems.forEach(function(navItem) {
15+
const navLink = navItem.querySelector(':scope > a');
16+
const details = navItem.querySelector(':scope > details');
17+
18+
if (!navLink || !details) return;
19+
20+
// Handle click on the nav link
21+
navLink.addEventListener('click', function(e) {
22+
// Toggle the details open/closed
23+
if (details.open) {
24+
// Currently open - close it
25+
details.open = false;
26+
e.preventDefault();
27+
e.stopPropagation();
28+
} else {
29+
// Currently closed - open it and navigate
30+
details.open = true;
31+
// Allow navigation to proceed
32+
}
33+
});
34+
});
35+
36+
// Expand only level 1 by default (shows categories like Algebraic, BBOB, etc.)
37+
expandableItems.forEach(function(navItem) {
38+
const details = navItem.querySelector(':scope > details');
39+
if (!details) return;
40+
41+
// Only expand L1 items (Test Functions, etc.)
42+
const isL1 = navItem.classList.contains('toctree-l1');
43+
44+
if (isL1) {
45+
details.open = true;
46+
}
47+
});
48+
});

‎docs/source/api_reference.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,10 @@ API Reference
77
Technical documentation for all classes and functions in Surfaces.
88

99
.. toctree::
10-
:maxdepth: 2
10+
:maxdepth: 3
1111

12-
api_reference/test_functions/index
13-
api_reference/base
14-
api_reference/visualization
12+
api_reference/base
13+
api_reference/test_functions/index
14+
api_reference/presets
15+
api_reference/noise
16+
api_reference/visualization

‎docs/source/api_reference/base.rst‎

Lines changed: 102 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,16 @@
11
.. _api_base:
22

3-
==============
3+
============
44
Base Classes
5-
==============
5+
============
66

7-
Base classes that all test functions inherit from.
7+
Base classes that all test functions inherit from. Understanding the hierarchy helps when creating custom test functions.
8+
9+
.. contents:: On this page
10+
:local:
11+
:depth: 2
12+
13+
----
814

915
BaseTestFunction
1016
================
@@ -16,19 +22,109 @@ The root class for all test functions in Surfaces.
1622
:undoc-members:
1723
:show-inheritance:
1824

25+
----
26+
27+
Algebraic Base Classes
28+
======================
29+
1930
AlgebraicFunction
20-
=================
31+
-----------------
2132

2233
Base class for algebraic (mathematical) test functions.
2334

2435
.. autoclass:: surfaces.test_functions.algebraic._base_algebraic_function.AlgebraicFunction
2536
:members:
2637
:show-inheritance:
2738

39+
BBOBFunction
40+
^^^^^^^^^^^^
41+
42+
Base class for BBOB (Black-Box Optimization Benchmarking) functions.
43+
44+
.. autoclass:: surfaces.test_functions.bbob._base_bbob.BBOBFunction
45+
:members:
46+
:show-inheritance:
47+
48+
CECFunction
49+
^^^^^^^^^^^
50+
51+
Base class for CEC competition benchmark functions.
52+
53+
.. autoclass:: surfaces.test_functions.cec._base_cec.CECFunction
54+
:members:
55+
:show-inheritance:
56+
57+
CEC2013Function
58+
"""""""""""""""
59+
60+
.. autoclass:: surfaces.test_functions.cec.cec2013._base_cec2013.CEC2013Function
61+
:members:
62+
:show-inheritance:
63+
64+
CEC2014Function
65+
"""""""""""""""
66+
67+
.. autoclass:: surfaces.test_functions.cec.cec2014._base_cec2014.CEC2014Function
68+
:members:
69+
:show-inheritance:
70+
71+
CEC2017Function
72+
"""""""""""""""
73+
74+
.. autoclass:: surfaces.test_functions.cec.cec2017._base_cec2017.CEC2017Function
75+
:members:
76+
:show-inheritance:
77+
78+
----
79+
80+
Machine Learning Base Classes
81+
=============================
82+
83+
MachineLearningFunction
84+
-----------------------
85+
86+
Base class for machine learning hyperparameter optimization functions.
87+
88+
.. autoclass:: surfaces.test_functions.machine_learning._base_machine_learning.MachineLearningFunction
89+
:members:
90+
:show-inheritance:
91+
92+
BaseTabular
93+
^^^^^^^^^^^
94+
95+
Base class for tabular data ML functions.
96+
97+
.. autoclass:: surfaces.test_functions.machine_learning.tabular._base_tabular.BaseTabular
98+
:members:
99+
:show-inheritance:
100+
101+
BaseImage
102+
^^^^^^^^^
103+
104+
Base class for image data ML functions.
105+
106+
.. autoclass:: surfaces.test_functions.machine_learning.image._base_image.BaseImage
107+
:members:
108+
:show-inheritance:
109+
110+
BaseTimeSeries
111+
^^^^^^^^^^^^^^
112+
113+
Base class for time series ML functions.
114+
115+
.. autoclass:: surfaces.test_functions.machine_learning.timeseries._base_timeseries.BaseTimeSeries
116+
:members:
117+
:show-inheritance:
118+
119+
----
120+
121+
Engineering Base Classes
122+
========================
123+
28124
EngineeringFunction
29-
===================
125+
-------------------
30126

31-
Base class for engineering design optimization problems.
127+
Base class for engineering design optimization problems with constraints.
32128

33129
.. autoclass:: surfaces.test_functions.engineering._base_engineering_function.EngineeringFunction
34130
:members:

‎docs/source/api_reference/noise.rst‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
.. _api_noise:
2+
3+
=====
4+
Noise
5+
=====
6+
7+
Noise layers for adding stochastic disturbances to test functions.
8+
9+
These classes can be passed to any test function to simulate noisy evaluations. Useful for testing algorithm robustness to measurement uncertainty.
10+
11+
.. contents:: On this page
12+
:local:
13+
:depth: 2
14+
15+
----
16+
17+
Base Class
18+
==========
19+
20+
.. autoclass:: surfaces.noise.BaseNoise
21+
:members:
22+
:show-inheritance:
23+
24+
----
25+
26+
Noise Types
27+
===========
28+
29+
GaussianNoise
30+
-------------
31+
32+
Additive Gaussian noise: ``f(x) + N(0, sigma^2)``
33+
34+
.. autoclass:: surfaces.noise.GaussianNoise
35+
:members:
36+
:show-inheritance:
37+
38+
UniformNoise
39+
------------
40+
41+
Additive uniform noise: ``f(x) + U(low, high)``
42+
43+
.. autoclass:: surfaces.noise.UniformNoise
44+
:members:
45+
:show-inheritance:
46+
47+
MultiplicativeNoise
48+
-------------------
49+
50+
Multiplicative noise: ``f(x) * (1 + N(0, sigma^2))``
51+
52+
.. autoclass:: surfaces.noise.MultiplicativeNoise
53+
:members:
54+
:show-inheritance:

0 commit comments

Comments
 (0)