[DOC] add python examples via 'literalinclude' and a testing CI

Author: SimonBlanke

.github/workflows/docs.yml

@@ -0,0 +1,90 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+    paths:
+      - 'docs/**'
+      - 'src/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches:
+      - main
+      - dev
+    paths:
+      - 'docs/**'
+      - 'src/**'
+      - '.github/workflows/docs.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test-snippets:
+    name: test-doc-snippets
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[all_extras,test]"
+          python -m pip install -r docs/requirements.txt
+
+      - name: Show dependencies
+        run: python -m pip list
+
+      - name: Test documentation snippets
+        run: |
+          python -m pytest docs/tests/test_doc_snippets.py -v --tb=short
+
+  build-docs:
+    name: build-docs
+    runs-on: ubuntu-latest
+    needs: test-snippets
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[all_extras]"
+          python -m pip install -r docs/requirements.txt
+
+      - name: Show dependencies
+        run: python -m pip list
+
+      - name: Build documentation
+        run: |
+          cd docs && sphinx-build -b html source build/html -W --keep-going
+
+      - name: Run doctest
+        run: |
+          cd docs && sphinx-build -b doctest source build/doctest || true
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/build/html/
+          retention-days: 7

docs/source/_snippets/__init__.py

@@ -0,0 +1,12 @@
+"""Documentation code snippets.
+
+This package contains testable Python code snippets that are included in the
+documentation using Sphinx's ``literalinclude`` directive. Each snippet file
+can be executed directly to verify it works correctly.
+
+The snippets are organized by documentation section:
+- getting_started/: Quick start examples
+- installation/: Installation verification examples
+- user_guide/: In-depth tutorial examples
+- examples/: Gallery examples
+"""

docs/source/_snippets/conftest.py

@@ -0,0 +1,46 @@
+"""Pytest configuration for documentation snippets.
+
+This conftest provides shared fixtures that snippet files can use for testing.
+The fixtures ensure consistent behavior across all snippet tests.
+"""
+
+import numpy as np
+import pytest
+
+
+@pytest.fixture
+def simple_search_space():
+    """Simple search space for basic examples."""
+    return {
+        "x": np.arange(-5, 5, 0.1),
+        "y": np.arange(-5, 5, 0.1),
+    }
+
+
+@pytest.fixture
+def simple_objective():
+    """Simple objective function for basic examples."""
+
+    def objective(params):
+        x = params["x"]
+        y = params["y"]
+        return -(x**2 + y**2)
+
+    return objective
+
+
+@pytest.fixture
+def sklearn_data():
+    """Load iris dataset for sklearn examples."""
+    from sklearn.datasets import load_iris
+
+    return load_iris(return_X_y=True)
+
+
+@pytest.fixture
+def sklearn_train_test_split(sklearn_data):
+    """Split sklearn data into train and test sets."""
+    from sklearn.model_selection import train_test_split
+
+    X, y = sklearn_data
+    return train_test_split(X, y, test_size=0.2, random_state=42)

docs/source/_snippets/examples/__init__.py

@@ -0,0 +1 @@
+"""Example gallery code snippets for documentation."""

docs/source/_snippets/getting_started/__init__.py

@@ -0,0 +1 @@
+"""Getting started code snippets for documentation."""

docs/source/_snippets/getting_started/bayesian_optimizer.py

@@ -0,0 +1,41 @@
+"""Bayesian Optimizer example for documentation.
+
+This snippet demonstrates the usage of BayesianOptimizer for
+optimization problems. It is included in get_started.rst.
+"""
+
+# [start:full_example]
+from hyperactive.opt.gfo import BayesianOptimizer
+# [end:full_example]
+
+# Need to define experiment and search_space for standalone execution
+import numpy as np
+
+
+def experiment(params):
+    """Simple objective function."""
+    x = params["x"]
+    y = params["y"]
+    return -(x**2 + y**2)
+
+
+search_space = {
+    "x": np.arange(-5, 5, 0.1),
+    "y": np.arange(-5, 5, 0.1),
+}
+
+# [start:optimizer_usage]
+optimizer = BayesianOptimizer(
+    search_space=search_space,
+    n_iter=30,
+    experiment=experiment,
+)
+best_params = optimizer.solve()
+# [end:optimizer_usage]
+
+if __name__ == "__main__":
+    print(f"Best parameters: {best_params}")
+    # Verify the optimization found parameters close to (0, 0)
+    assert abs(best_params["x"]) < 2.0, f"Expected x near 0, got {best_params['x']}"
+    assert abs(best_params["y"]) < 2.0, f"Expected y near 0, got {best_params['y']}"
+    print("Bayesian optimizer example passed!")

docs/source/_snippets/getting_started/index_bayesian.py

@@ -0,0 +1,36 @@
+"""Bayesian optimization example for index page.
+
+This snippet demonstrates Bayesian optimization with a more complex
+objective function shown on the landing page. It is included in index.rst.
+"""
+
+# [start:full_example]
+import numpy as np
+from hyperactive.opt.gfo import BayesianOptimizer
+
+
+def complex_objective(params):
+    x = params["x"]
+    y = params["y"]
+    return -((x - 2) ** 2 + (y + 1) ** 2) + np.sin(x * y)
+
+
+search_space = {
+    "x": np.linspace(-5, 5, 100),
+    "y": np.linspace(-5, 5, 100),
+}
+
+optimizer = BayesianOptimizer(
+    search_space=search_space,
+    n_iter=50,
+    experiment=complex_objective,
+)
+best_params = optimizer.solve()
+# [end:full_example]
+
+if __name__ == "__main__":
+    print(f"Best parameters: {best_params}")
+    # Verify we got valid parameters
+    assert "x" in best_params
+    assert "y" in best_params
+    print("Index Bayesian example passed!")

docs/source/_snippets/getting_started/index_custom_function.py

@@ -0,0 +1,38 @@
+"""Custom function example for index page.
+
+This snippet demonstrates the basic custom function optimization
+shown on the landing page. It is included in index.rst.
+"""
+
+# [start:full_example]
+import numpy as np
+from hyperactive.opt.gfo import HillClimbing
+
+
+# Define your objective function
+def objective(params):
+    x, y = params["x"], params["y"]
+    return -(x**2 + y**2)  # Maximize (minimize negative)
+
+
+# Define the search space
+search_space = {
+    "x": np.arange(-5, 5, 0.1),
+    "y": np.arange(-5, 5, 0.1),
+}
+
+# Create optimizer and solve
+optimizer = HillClimbing(
+    search_space=search_space,
+    n_iter=100,
+    experiment=objective,
+)
+best_params = optimizer.solve()
+print(f"Best parameters: {best_params}")
+# [end:full_example]
+
+if __name__ == "__main__":
+    # Verify the optimization found parameters close to (0, 0)
+    assert abs(best_params["x"]) < 1.0, f"Expected x near 0, got {best_params['x']}"
+    assert abs(best_params["y"]) < 1.0, f"Expected y near 0, got {best_params['y']}"
+    print("Index custom function example passed!")

docs/source/_snippets/getting_started/index_sklearn_tuning.py

@@ -0,0 +1,34 @@
+"""Scikit-learn tuning example for index page.
+
+This snippet demonstrates sklearn integration using OptCV
+shown on the landing page. It is included in index.rst.
+"""
+
+# [start:full_example]
+from sklearn.svm import SVC
+from sklearn.datasets import load_iris
+from sklearn.model_selection import train_test_split
+from hyperactive.integrations.sklearn import OptCV
+from hyperactive.opt.gfo import HillClimbing
+
+# Load data
+X, y = load_iris(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(X, y)
+
+# Define optimizer with search space
+search_space = {"kernel": ["linear", "rbf"], "C": [0.1, 1, 10]}
+optimizer = HillClimbing(search_space=search_space, n_iter=20)
+
+# Create tuned estimator and fit
+tuned_svc = OptCV(SVC(), optimizer)
+tuned_svc.fit(X_train, y_train)
+
+print(f"Best params: {tuned_svc.best_params_}")
+# [end:full_example]
+
+if __name__ == "__main__":
+    # Verify we got valid results
+    assert hasattr(tuned_svc, "best_params_")
+    assert "kernel" in tuned_svc.best_params_
+    assert "C" in tuned_svc.best_params_
+    print("Index sklearn tuning example passed!")

docs/source/_snippets/getting_started/quick_start.py

@@ -0,0 +1,40 @@
+"""Quick start example for documentation.
+
+This snippet demonstrates the basic usage of Hyperactive for optimizing
+a custom objective function. It is included in get_started.rst.
+"""
+
+# [start:full_example]
+import numpy as np
+from hyperactive.opt.gfo import HillClimbing
+
+
+# 1. Define your objective function
+def objective(params):
+    x = params["x"]
+    y = params["y"]
+    return -(x**2 + y**2)  # Hyperactive maximizes by default
+
+
+# 2. Define the search space
+search_space = {
+    "x": np.arange(-5, 5, 0.1),
+    "y": np.arange(-5, 5, 0.1),
+}
+
+# 3. Create an optimizer and solve
+optimizer = HillClimbing(
+    search_space=search_space,
+    n_iter=100,
+    experiment=objective,
+)
+best_params = optimizer.solve()
+
+print(f"Best parameters: {best_params}")
+# [end:full_example]
+
+if __name__ == "__main__":
+    # Verify the optimization found parameters close to (0, 0)
+    assert abs(best_params["x"]) < 1.0, f"Expected x near 0, got {best_params['x']}"
+    assert abs(best_params["y"]) < 1.0, f"Expected y near 0, got {best_params['y']}"
+    print("Quick start example passed!")