Merge pull request #43 from automl/docs

Setup for automated doc generation via mkdocs
automl · Jul 22, 2023 · 24b9409 · 24b9409
2 parents 8b6d373 + bb2f2c8
commit 24b9409
Show file tree

Hide file tree

Showing 30 changed files with 148 additions and 216 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -7,13 +7,13 @@ on:
   # Trigger on any push to the main
   push:
     branches:
-      - main
+      - master
       - development
 
   # Trigger on any push to a PR that targets main
   pull_request:
     branches:
-      - main
+      - master
       - development
 
 permissions:
@@ -23,49 +23,16 @@ env:
   name: DEHB
 
 jobs:
-  build-and-deploy:
+  deploy:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v2
-
-    - name: Setup Python
-      uses: actions/setup-python@v2
-      with:
-        python-version: "3.8"
-
-    - name: Install dependencies
-      run: |
-        pip install ".[dev]"
-
-    - name: Make docs
-      run: |
-        make clean
-        make docs
-
-    - name: Pull latest gh-pages
-      if: (contains(github.ref, 'development') || contains(github.ref, 'main'))
-      run: |
-        cd ..
-        git clone https://github.com/${{ github.repository }}.git --branch gh-pages --single-branch gh-pages
-
-    - name: Copy new docs into gh-pages
-      if: (contains(github.ref, 'development') || contains(github.ref, 'main'))
-      run: |
-        branch_name=${GITHUB_REF##*/}
-        cd ../gh-pages
-        rm -rf $branch_name
-        cp -r ../${{ env.name }}/docs/build/html $branch_name
-
-    - name: Push to gh-pages
-      if: (contains(github.ref, 'development') || contains(github.ref, 'main'))
-      run: |
-        last_commit=$(git log --pretty=format:"%an: %s")
-        cd ../gh-pages
-        branch_name=${GITHUB_REF##*/}
-        git add $branch_name/
-        git config --global user.name 'Github Actions'
-        git config --global user.email '[email protected]'
-        git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
-        git commit -am "$last_commit"
-        git push
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v3
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install "mkdocs-material" "mkdocstrings[python]"
+      - run: mkdocs gh-deploy --force
diff --git a/.github/workflows/pytest.yml b/.github/workflows/pytest.yml
@@ -7,13 +7,13 @@ on:
   # Triggers with push to main
   push:
     branches:
-      - main
+      - master
       - development
 
   # Triggers with push to a PR aimed at main
   pull_request:
     branches:
-      - main
+      - master
       - development
 
   schedule:

diff --git a/README.md b/README.md
@@ -1,6 +1,7 @@
 # DEHB: Evolutionary Hyperband for Scalable, Robust and Efficient Hyperparameter Optimization
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Tests](https://github.com/automl/DEHB/actions/workflows/pytest.yml/badge.svg)](https://github.com/automl/DEHB/actions/workflows/pytest.yml)
+[![docs](https://github.com/automl/DEHB/actions/workflows/docs.yml/badge.svg)](https://github.com/automl/DEHB/actions/workflows/docs.yml)
 [![Coverage Status](https://coveralls.io/repos/github/automl/DEHB/badge.svg)](https://coveralls.io/github/automl/DEHB)
 [![PyPI](https://img.shields.io/pypi/v/dehb)](https://pypi.org/project/dehb/)
 [![Static Badge](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20-blue)](https://pypi.org/project/dehb/)

diff --git a/dehb/__init__.py b/dehb/__init__.py
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/advanced_usage/index.rst b/docs/advanced_usage/index.rst
diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/assets/automl_org.png b/docs/assets/automl_org.png
diff --git a/docs/basic_usage/index.rst b/docs/basic_usage/index.rst
diff --git a/docs/commands.rst b/docs/commands.rst
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/faq.rst b/docs/faq.rst
diff --git a/docs/glossary.rst b/docs/glossary.rst
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,3 @@
+# Welcome to DEHB
+
+Evolutionary Hyperband for Scalable, Robust and Efficient Hyperparameter Optimization.
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/installation.rst b/docs/installation.rst
diff --git a/docs/references/bracket_manager.md b/docs/references/bracket_manager.md
@@ -0,0 +1,3 @@
+# Bracket manager
+
+::: dehb.utils.bracket_manager
diff --git a/docs/references/de.md b/docs/references/de.md
@@ -0,0 +1,3 @@
+# DE
+
+::: dehb.optimizers.de
diff --git a/docs/references/dehb.md b/docs/references/dehb.md
@@ -0,0 +1,3 @@
+# DEHB
+
+::: dehb.optimizers.dehb
diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,6 @@
+Examples
+========
+
+We provide several examples of how to use DEHB with Python. The examples were structured in order to give the user an
+introduction to the interface of DEHB and how to use it. Moreover the examples show how to use DEHB with and without
+the ConfigSpace library and an exemplary optimization with PyTorch. 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,72 @@
+site_name: DEHB
+
+nav:
+  - Home: index.md
+  - Code Reference:
+    - DEHB: references/dehb.md
+    - DE: references/de.md
+    - Bracket Manager: references/bracket_manager.md
+
+theme:
+  name: material
+  logo: assets/automl_org.png
+  favicon: assets/automl_org.png
+  icon:
+    repo: fontawesome/brands/github
+  features:
+    - content.code.annotate
+    - content.code.copy
+    - navigation.footer
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - toc.follow
+    - header.autohide
+    - search.suggest
+    - search.highlight
+    - search.share
+  font:
+    text: Roboto
+    code: Roboto Mono
+  palette:
+    - scheme: slate
+      media: "(prefers-color-scheme: dark)"
+      primary: indigo
+      accent: deep purple
+      toggle:
+        icon: material/eye-outline
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - scheme: default
+      media: "(prefers-color-scheme: light)"
+      primary: indigo
+      accent: deep purple
+      toggle:
+        icon: material/eye
+        name: Switch to dark mode
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      enable_inventory: true
+      custom_templates: docs/_templates
+      handlers:
+        python:
+          paths: [src]
+          options:  # https://mkdocstrings.github.io/python/usage/
+            docstring_section_style: spacy
+            show_docstring_attributes: true
+            show_docstring_description: true
+            show_root_heading: false
+            show_root_toc_entry: false
+            show_object_full_path: false
+            merge_init_into_class: true
+            docstring_style: google
+            show_if_no_docstring: false
+            show_bases: true
+            show_source: true
+            members_order: "source"
+            show_signature: true
+            separate_signature: false
+            show_signature_annotations: false
diff --git a/dehb/README.md → src/dehb/README.md b/dehb/README.md → src/dehb/README.md
diff --git a/src/dehb/__init__.py b/src/dehb/__init__.py
@@ -0,0 +1,11 @@
+import datetime
+from .optimizers import DE, AsyncDE
+from .optimizers import DEHB
+from .utils import SHBracketManager
+
+name = "DEHB"
+author = (
+    "N. Awad and N. Mallik and F. Hutter"
+)
+copyright = f"Copyright {datetime.date.today().strftime('%Y')}, Noor Awad, Neeratyoy Mallik and Frank Hutter"
+version = "0.0.5"
diff --git a/dehb/optimizers/__init__.py → src/dehb/optimizers/__init__.py b/dehb/optimizers/__init__.py → src/dehb/optimizers/__init__.py
diff --git a/dehb/optimizers/de.py → src/dehb/optimizers/de.py b/dehb/optimizers/de.py → src/dehb/optimizers/de.py