Migrate docs (#1155)

* docs(installation): add install instructs for windows to be precise: point to the github issue bc there are probably many ways to Rome but not able to test it * docs(links): fix redirection * docs(installation): rst -> md * docs(package_overview): rst -> md * docs(getting_started): rst -> md * docs(minimal_example): rst -> md * docs(references): rst -> md * docs(glossary): rst -> md but links do not work yet * docs(faq): rst -> md * docs(license): rst -> md * docs(experimental): rst -> md * Rename file * renaem old files * docs: add hooks * docs: add mkdocs config * docs(components): rst -> md API links not yet working * refactor(acquisition_maximizer): fix typo * docs(component): fix links * docs(2_multi_fidelity): rst -> md * docs(1_components): fix links * docs(api_generator): fix link generation * docs(3_multi_objective): rst -> md * docs(4_instances): rst -> md * docs(5.1_warmstarting): rst -> md * Fix link * docs(5_ask_and_tell): rst -> md * docs(6_commandline): rst -> md * docs(7_stopping_criteria): rst -> md * docs(8_logging): rst -> md * docs(9_parallelism): rst -> md * docs(10_continue): rst -> md * docs(11_reproducibility): rst -> md * docs(12_optimzations): rst -> md * docs(examples): hide turbo and boing * docs(examples): rst -> md * docs(examples): fix tiny * docs(examples): fix navigation sections * docs(examples): fix navigation sections * fix typo * Update * ignore more * docs(docstring): fix refs * docs(docstring): fix refs * docs(home): add sections * build(setup): add requirements for mkdocs * refactor(abstract_intensifier): track param max_config_calls * refactor(docs): remove old files * refactor(acquisition): fix 'acqusition' typo * Update CHANGELOG.md * docs(examples): flags to run when building (does not work yet) * Update Makefile * Update CHANGELOG.md * Fix links * Update github workflow for doc building * docs(3_getting_started): fix links * Minor modifications * docs(constants): add docstring * docs(multi_objective): fix broken link * docs(ask_and_tell): fix broken link * docs(parallelism.md): fix broken link * docs(continue): fix broken link * delete .rst * Fix sidebar navigatoon * update CHANGELOG.md --------- Co-authored-by: benjamc <[email protected]> Co-authored-by: Lukas Fehring <[email protected]>
automl · Nov 21, 2024 · a154cf6 · a154cf6
1 parent ca1424b
commit a154cf6
Show file tree

Hide file tree

Showing 91 changed files with 1,670 additions and 1,235 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -1,89 +1,27 @@
+# This workflow is just to test that the docs build successfully.
 name: docs
-
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 on:
-  # Manual trigger option in GitHub
-  # This won't push to GitHub pages where docs are hosted due
-  # to the guarded if statement in those steps
   workflow_dispatch:
-
-  # Trigger on push to these branches
   push:
     branches:
       - main
-      - development
-
-  # Trigger on open/push to a PR targeting one of these branches
   pull_request:
-    types:
-      - opened
-      - synchronize
-      - reopened
-      - ready_for_review
     branches:
       - main
-      - development
-
-env:
-  name: SMAC3
-
+permissions:
+  contents: write
 jobs:
-  build-and-deploy:
-    if: ${{ !github.event.pull_request.draft }}
+  build:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v4
-
-    - name: Setup Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: "3.10"
-
-    - name: Install dependencies
-      id: install
-      run: |
-        pip install ".[gpytorch,dev]"
-
-        # Getting the version
-        SMAC_VERSION=$(python -c "import smac; print('v' + str(smac.version));")
-
-        # Make it a global variable
-        echo "SMAC_VERSION=$SMAC_VERSION" >> $GITHUB_ENV
-
-    - name: Make docs
-      run: |
-        make clean
-        make docs
-
-    - name: Pull latest gh-pages
-      if: (contains(github.ref, 'develop') || contains(github.ref, 'main')) && github.event_name == 'push'
-      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, 'develop') || contains(github.ref, 'main')) && github.event_name == 'push'
-      run: |
-        branch_name=${GITHUB_REF##*/}
-        cd ../gh-pages
-        rm -rf $branch_name
-        cp -r ../${{ env.name }}/docs/build/html $branch_name
-
-        # we also copy the current SMAC_VERSION
-        rm -rf $SMAC_VERSION
-        cp -r ../${{ env.name }}/docs/build/html $SMAC_VERSION
-
-
-    - name: Push to gh-pages
-      if: (contains(github.ref, 'develop') || contains(github.ref, 'main')) && github.event_name == 'push'
-      run: |
-        last_commit=$(git log --pretty=format:"%an: %s")
-        cd ../gh-pages
-        branch_name=${GITHUB_REF##*/}
-        git add $branch_name/
-        git add $SMAC_VERSION/
-        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@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: "Install dependancies"
+        run: python -m pip install -e ".[dev]"
+      - name: "Build Docs"
+        run: mkdocs build --clean --strict
diff --git a/.gitignore b/.gitignore
@@ -147,4 +147,7 @@ src
 
 # Pycharm
 .idea
-.vscode
+.vscode
+
+projects
+_api
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,10 @@
+# 2.3.0
+
+## Documentation
+- Update windows install guide (#952)
+- Correct intensifier for Algorithm Configuration Facade (#1162, #1165)
+- Migrate sphinx docs to mkdocs (#1155)
+
 # 2.2.1
 
 ## Improvements
@@ -688,7 +695,7 @@ Since many urgent features were already taken care of in 0.14.0, this release ma
   conditions when starting multiple runs on a cluster.
 * MAINT #209: adds the seed or a pseudo-seed to the output directory name for
   better identifiability of the output directories.
-* FIX #216: replace broken call to in EIPS acqusition function.
+* FIX #216: replace broken call to in EIPS acquisition function.
 * MAINT: use codecov.io instead of coveralls.io.
 * MAINT: increase minimal required version of the ConfigSpace package to 0.3.2.
 

diff --git a/Makefile b/Makefile
@@ -86,27 +86,37 @@ format: format-black format-isort
 tests:
 	$(PYTEST) ${TESTS_DIR}
 
+# Launch the docs, executing code blocks and examples
+docs-full:
+	$(PYTHON) -m webbrowser -t "http://127.0.0.1:8000/"
+	SMAC_DOC_RENDER_EXAMPLES=all \
+		SMAC_DOCS_OFFLINE=true \
+		SMAC_EXEC_DOCS=true \
+		mkdocs serve --watch-theme
+
+# Launch the docs and execute code blocks
+docs-code:
+	$(PYTHON) -m webbrowser -t "http://127.0.0.1:8000/"
+	SMAC_DOCS_OFFLINE=true \
+		SMAC_EXEC_DOCS=true \
+		SMAC_DOC_RENDER_EXAMPLES=false \
+		mkdocs serve --watch-theme
+
+# Launch the docs but dont run code examples
 docs:
-	$(MAKE) -C ${DOCDIR} docs
-	@echo
-	@echo "View docs at:"
-	@echo ${INDEX_HTML}
-
-examples:
-	$(MAKE) -C ${DOCDIR} examples
-	@echo
-	@echo "View docs at:"
-	@echo ${INDEX_HTML}
+	$(PYTHON) -m webbrowser -t "http://127.0.0.1:8000/"
+	SMAC_DOCS_OFFLINE=true \
+		SMAC_EXEC_DOCS=false \
+		SMAC_DOC_RENDER_EXAMPLES=false \
+		mkdocs serve --watch-theme
+	# https://github.com/pawamoy/markdown-exec/issues/19
 
 # Build a distribution in ./dist
 build:
 	$(PYTHON) setup.py sdist
 
 clean: clean-build clean-docs clean-data
 
-clean-docs:
-	$(MAKE) -C ${DOCDIR} clean
-
 clean-build:
 	$(PYTHON) setup.py clean
 	rm -rf ${DIST}

diff --git a/docs/10_experimental.rst → docs/10_experimental.md b/docs/10_experimental.rst → docs/10_experimental.md
@@ -1,12 +1,10 @@
-Experimental
-============
+# Experimental
 
-.. warning::
+!!! warning
     This part is experimental and might not work in each case. If you would like to suggest any changes, please let us know. 
 
 
-Installation in Windows via WSL
-------------------------------
+## Installation in Windows via WSL
 
 SMAC can be installed in a WSL (Windows Subsystem for Linux) under Windows.
 
@@ -21,28 +19,31 @@ Download an Anaconda Linux version to drive D under Windows, e.g. D:\\Anaconda3-
 
 In the WSL, Windows resources are mounted under /mnt:
 
-.. code:: bash
-
-    cd /mnt/d
-    bash Anaconda3-2023.03-1-Linux-x86_64
+```bash
+cd /mnt/d
+bash Anaconda3-2023.03-1-Linux-x86_64
+```
 
 Enter this command to create the environment variable:
 
-.. code:: bash
-
-    export PATH="$PATH:/home/${USER}/anaconda3/bin
+```bash
+export PATH="$PATH:/home/${USER}/anaconda3/bin
+```
 
-Input 'python' to check if the installation was successful.
+Input `python` to check if the installation was successful.
 
 **3) Install SMAC**
 
 Change to your home folder and install the general software there:
 
-.. code:: bash
-
-    cd /home/${USER}
-    sudo apt-get install software-properties-common
-    sudo apt-get update
-    sudo apt-get install build-essential swig
-    conda install gxx_linux-64 gcc_linux-64 swig
-    curl https://raw.githubusercontent.com/automl/smac3/master/requirements.txt | xargs -n 1 -L 1 pip install
+```bash
+cd /home/${USER}
+sudo apt-get install software-properties-common
+sudo apt-get update
+sudo apt-get install build-essential swig
+conda install gxx_linux-64 gcc_linux-64 swig
+curl https://raw.githubusercontent.com/automl/smac3/master/requirements.txt | xargs -n 1 -L 1 pip install
+```
+
+## Installation in Pure Windows
+Please refer to this [issue](https://github.com/automl/SMAC3/issues/952) for installation instructions for SMAC3-1.4 and SMAC3-2.x.
diff --git a/docs/1_installation.md b/docs/1_installation.md
@@ -0,0 +1,72 @@
+# Installation
+
+## Requirements
+
+SMAC is written in python3 and therefore requires an environment with python>=3.8.
+Furthermore, the Random Forest used in SMAC requires SWIG as a build dependency.
+
+!!! info 
+
+    SMAC is tested on Linux and Mac machines with python >=3.8.
+
+
+## SetUp
+
+We recommend using Anaconda to create and activate an environment:
+
+```bash
+conda create -n SMAC python=3.10
+conda activate SMAC
+```
+
+Now install swig either on the system level e.g. using the following command for Linux:
+```bash
+apt-get install swig
+```
+
+Or install swig inside of an already created conda environment using:
+
+```bash
+conda install gxx_linux-64 gcc_linux-64 swig
+```
+
+## Install SMAC
+You can install SMAC either using PyPI or Conda-forge.
+
+### PYPI
+To install SMAC with PyPI call:
+
+```bash
+pip install smac
+```
+
+Or alternatively, clone the environment from GitHub directly:
+
+```bash
+git clone https://github.com/automl/SMAC3.git && cd SMAC3
+pip install -e ".[dev]"
+```
+
+### Conda-forge
+
+Installing SMAC from the `conda-forge` channel can be achieved by adding `conda-forge` to your channels with:
+
+```bash
+conda config --add channels conda-forge
+conda config --set channel_priority strict
+```
+
+You must have `conda >= 4.9` installed. To update conda or check your current conda version, please follow the instructions from [the official anaconda documentation](https://docs.anaconda.com/anaconda/install/update-version/). Once the `conda-forge` channel has been enabled, SMAC can be installed with:
+
+```bash
+conda install smac
+```
+
+Read [SMAC feedstock](https://github.com/conda-forge/smac-feedstock) for more details.
+
+## Windows (native or via WSL, experimental)
+
+SMAC can be installed under Windows in a WSL (Windows Subsystem for Linux). 
+You can find an instruction on how to do this here: [Experimental](./10_experimental.md).
+However, this is experimental and might not work in each case. 
+If you would like to suggest any changes, please let us know.
-Original file line number
+Diff line change
@@ Expand Up / @@ -147,4 +147,7 @@ src @@
     # Pycharm
     .idea
-    .vscode
+    .vscode
+    projects
+    _api