Skip to content

Commit a154cf6

Browse files
benjamcLukasFehring
benjamc
and
LukasFehring
authored
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]>
1 parent ca1424b commit a154cf6

File tree

91 files changed

+1670
-1235
lines changed

Some content is hidden

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

91 files changed

+1670
-1235
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 15 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,27 @@
1+
# This workflow is just to test that the docs build successfully.
12
name: docs
2-
3+
concurrency:
4+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
5+
cancel-in-progress: true
36
on:
4-
# Manual trigger option in GitHub
5-
# This won't push to GitHub pages where docs are hosted due
6-
# to the guarded if statement in those steps
77
workflow_dispatch:
8-
9-
# Trigger on push to these branches
108
push:
119
branches:
1210
- main
13-
- development
14-
15-
# Trigger on open/push to a PR targeting one of these branches
1611
pull_request:
17-
types:
18-
- opened
19-
- synchronize
20-
- reopened
21-
- ready_for_review
2212
branches:
2313
- main
24-
- development
25-
26-
env:
27-
name: SMAC3
28-
14+
permissions:
15+
contents: write
2916
jobs:
30-
build-and-deploy:
31-
if: ${{ !github.event.pull_request.draft }}
17+
build:
3218
runs-on: ubuntu-latest
3319
steps:
34-
- name: Checkout
35-
uses: actions/checkout@v4
36-
37-
- name: Setup Python
38-
uses: actions/setup-python@v5
39-
with:
40-
python-version: "3.10"
41-
42-
- name: Install dependencies
43-
id: install
44-
run: |
45-
pip install ".[gpytorch,dev]"
46-
47-
# Getting the version
48-
SMAC_VERSION=$(python -c "import smac; print('v' + str(smac.version));")
49-
50-
# Make it a global variable
51-
echo "SMAC_VERSION=$SMAC_VERSION" >> $GITHUB_ENV
52-
53-
- name: Make docs
54-
run: |
55-
make clean
56-
make docs
57-
58-
- name: Pull latest gh-pages
59-
if: (contains(github.ref, 'develop') || contains(github.ref, 'main')) && github.event_name == 'push'
60-
run: |
61-
cd ..
62-
git clone https://github.com/${{ github.repository }}.git --branch gh-pages --single-branch gh-pages
63-
64-
- name: Copy new docs into gh-pages
65-
if: (contains(github.ref, 'develop') || contains(github.ref, 'main')) && github.event_name == 'push'
66-
run: |
67-
branch_name=${GITHUB_REF##*/}
68-
cd ../gh-pages
69-
rm -rf $branch_name
70-
cp -r ../${{ env.name }}/docs/build/html $branch_name
71-
72-
# we also copy the current SMAC_VERSION
73-
rm -rf $SMAC_VERSION
74-
cp -r ../${{ env.name }}/docs/build/html $SMAC_VERSION
75-
76-
77-
- name: Push to gh-pages
78-
if: (contains(github.ref, 'develop') || contains(github.ref, 'main')) && github.event_name == 'push'
79-
run: |
80-
last_commit=$(git log --pretty=format:"%an: %s")
81-
cd ../gh-pages
82-
branch_name=${GITHUB_REF##*/}
83-
git add $branch_name/
84-
git add $SMAC_VERSION/
85-
git config --global user.name 'Github Actions'
86-
git config --global user.email '[email protected]'
87-
git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
88-
git commit -am "$last_commit"
89-
git push
20+
- uses: actions/checkout@v4
21+
- uses: actions/setup-python@v5
22+
with:
23+
python-version: "3.10"
24+
- name: "Install dependancies"
25+
run: python -m pip install -e ".[dev]"
26+
- name: "Build Docs"
27+
run: mkdocs build --clean --strict

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,4 +147,7 @@ src
147147

148148
# Pycharm
149149
.idea
150-
.vscode
150+
.vscode
151+
152+
projects
153+
_api

‎CHANGELOG.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
# 2.3.0
2+
3+
## Documentation
4+
- Update windows install guide (#952)
5+
- Correct intensifier for Algorithm Configuration Facade (#1162, #1165)
6+
- Migrate sphinx docs to mkdocs (#1155)
7+
18
# 2.2.1
29

310
## Improvements
@@ -688,7 +695,7 @@ Since many urgent features were already taken care of in 0.14.0, this release ma
688695
conditions when starting multiple runs on a cluster.
689696
* MAINT #209: adds the seed or a pseudo-seed to the output directory name for
690697
better identifiability of the output directories.
691-
* FIX #216: replace broken call to in EIPS acqusition function.
698+
* FIX #216: replace broken call to in EIPS acquisition function.
692699
* MAINT: use codecov.io instead of coveralls.io.
693700
* MAINT: increase minimal required version of the ConfigSpace package to 0.3.2.
694701

‎Makefile‎

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -86,27 +86,37 @@ format: format-black format-isort
8686
tests:
8787
$(PYTEST) ${TESTS_DIR}
8888

89+
# Launch the docs, executing code blocks and examples
90+
docs-full:
91+
$(PYTHON) -m webbrowser -t "http://127.0.0.1:8000/"
92+
SMAC_DOC_RENDER_EXAMPLES=all \
93+
SMAC_DOCS_OFFLINE=true \
94+
SMAC_EXEC_DOCS=true \
95+
mkdocs serve --watch-theme
96+
97+
# Launch the docs and execute code blocks
98+
docs-code:
99+
$(PYTHON) -m webbrowser -t "http://127.0.0.1:8000/"
100+
SMAC_DOCS_OFFLINE=true \
101+
SMAC_EXEC_DOCS=true \
102+
SMAC_DOC_RENDER_EXAMPLES=false \
103+
mkdocs serve --watch-theme
104+
105+
# Launch the docs but dont run code examples
89106
docs:
90-
$(MAKE) -C ${DOCDIR} docs
91-
@echo
92-
@echo "View docs at:"
93-
@echo ${INDEX_HTML}
94-
95-
examples:
96-
$(MAKE) -C ${DOCDIR} examples
97-
@echo
98-
@echo "View docs at:"
99-
@echo ${INDEX_HTML}
107+
$(PYTHON) -m webbrowser -t "http://127.0.0.1:8000/"
108+
SMAC_DOCS_OFFLINE=true \
109+
SMAC_EXEC_DOCS=false \
110+
SMAC_DOC_RENDER_EXAMPLES=false \
111+
mkdocs serve --watch-theme
112+
# https://github.com/pawamoy/markdown-exec/issues/19
100113

101114
# Build a distribution in ./dist
102115
build:
103116
$(PYTHON) setup.py sdist
104117

105118
clean: clean-build clean-docs clean-data
106119

107-
clean-docs:
108-
$(MAKE) -C ${DOCDIR} clean
109-
110120
clean-build:
111121
$(PYTHON) setup.py clean
112122
rm -rf ${DIST}

‎docs/10_experimental.rst‎ renamed to ‎docs/10_experimental.md‎

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,10 @@
1-
Experimental
2-
============
1+
# Experimental
32

4-
.. warning::
3+
!!! warning
54
This part is experimental and might not work in each case. If you would like to suggest any changes, please let us know.
65

76

8-
Installation in Windows via WSL
9-
------------------------------
7+
## Installation in Windows via WSL
108

119
SMAC can be installed in a WSL (Windows Subsystem for Linux) under Windows.
1210

@@ -21,28 +19,31 @@ Download an Anaconda Linux version to drive D under Windows, e.g. D:\\Anaconda3-
2119

2220
In the WSL, Windows resources are mounted under /mnt:
2321

24-
.. code:: bash
25-
26-
cd /mnt/d
27-
bash Anaconda3-2023.03-1-Linux-x86_64
22+
```bash
23+
cd /mnt/d
24+
bash Anaconda3-2023.03-1-Linux-x86_64
25+
```
2826

2927
Enter this command to create the environment variable:
3028

31-
.. code:: bash
32-
33-
export PATH="$PATH:/home/${USER}/anaconda3/bin
29+
```bash
30+
export PATH="$PATH:/home/${USER}/anaconda3/bin
31+
```
3432
35-
Input 'python' to check if the installation was successful.
33+
Input `python` to check if the installation was successful.
3634
3735
**3) Install SMAC**
3836
3937
Change to your home folder and install the general software there:
4038
41-
.. code:: bash
42-
43-
cd /home/${USER}
44-
sudo apt-get install software-properties-common
45-
sudo apt-get update
46-
sudo apt-get install build-essential swig
47-
conda install gxx_linux-64 gcc_linux-64 swig
48-
curl https://raw.githubusercontent.com/automl/smac3/master/requirements.txt | xargs -n 1 -L 1 pip install
39+
```bash
40+
cd /home/${USER}
41+
sudo apt-get install software-properties-common
42+
sudo apt-get update
43+
sudo apt-get install build-essential swig
44+
conda install gxx_linux-64 gcc_linux-64 swig
45+
curl https://raw.githubusercontent.com/automl/smac3/master/requirements.txt | xargs -n 1 -L 1 pip install
46+
```
47+
48+
## Installation in Pure Windows
49+
Please refer to this [issue](https://github.com/automl/SMAC3/issues/952) for installation instructions for SMAC3-1.4 and SMAC3-2.x.

‎docs/1_installation.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Installation
2+
3+
## Requirements
4+
5+
SMAC is written in python3 and therefore requires an environment with python>=3.8.
6+
Furthermore, the Random Forest used in SMAC requires SWIG as a build dependency.
7+
8+
!!! info
9+
10+
SMAC is tested on Linux and Mac machines with python >=3.8.
11+
12+
13+
## SetUp
14+
15+
We recommend using Anaconda to create and activate an environment:
16+
17+
```bash
18+
conda create -n SMAC python=3.10
19+
conda activate SMAC
20+
```
21+
22+
Now install swig either on the system level e.g. using the following command for Linux:
23+
```bash
24+
apt-get install swig
25+
```
26+
27+
Or install swig inside of an already created conda environment using:
28+
29+
```bash
30+
conda install gxx_linux-64 gcc_linux-64 swig
31+
```
32+
33+
## Install SMAC
34+
You can install SMAC either using PyPI or Conda-forge.
35+
36+
### PYPI
37+
To install SMAC with PyPI call:
38+
39+
```bash
40+
pip install smac
41+
```
42+
43+
Or alternatively, clone the environment from GitHub directly:
44+
45+
```bash
46+
git clone https://github.com/automl/SMAC3.git && cd SMAC3
47+
pip install -e ".[dev]"
48+
```
49+
50+
### Conda-forge
51+
52+
Installing SMAC from the `conda-forge` channel can be achieved by adding `conda-forge` to your channels with:
53+
54+
```bash
55+
conda config --add channels conda-forge
56+
conda config --set channel_priority strict
57+
```
58+
59+
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:
60+
61+
```bash
62+
conda install smac
63+
```
64+
65+
Read [SMAC feedstock](https://github.com/conda-forge/smac-feedstock) for more details.
66+
67+
## Windows (native or via WSL, experimental)
68+
69+
SMAC can be installed under Windows in a WSL (Windows Subsystem for Linux).
70+
You can find an instruction on how to do this here: [Experimental](./10_experimental.md).
71+
However, this is experimental and might not work in each case.
72+
If you would like to suggest any changes, please let us know.

0 commit comments

Comments
 (0)