Deploy a new doc website (#338)

A new documentation website. And:

* add actions for doc

* update docstr

* installation instructions for doc dev

* unify README and Getting Started

* rename notebook

* doc about best_model_for_estimator #340

* docstr for keep_search_state #340

* DNN

Co-authored-by: Qingyun Wu <[email protected]>
Co-authored-by: Z.sk <[email protected]>

.devcontainer/Dockerfile

@@ -3,15 +3,15 @@
 # Licensed under the MIT License. See LICENSE file in the project root for license information.
 #-------------------------------------------------------------------------------------------------------------
 
-FROM mcr.microsoft.com/vscode/devcontainers/python:0-3.7
+FROM mcr.microsoft.com/vscode/devcontainers/python:0-3.9
 
 #
 # Update the OS and maybe install packages
 #
 ENV DEBIAN_FRONTEND=noninteractive
 RUN apt-get update \
    && apt-get upgrade -y  \
-   && apt-get -y install --no-install-recommends build-essential \
+   && apt-get -y install --no-install-recommends build-essential npm \
    && apt-get autoremove -y \
    && apt-get clean -y \
    && rm -rf /var/lib/apt/lists/*
@@ -20,4 +20,7 @@ ENV DEBIAN_FRONTEND=dialog
 #
 # Install extras for development
 #
-RUN pip3 --disable-pip-version-check --no-cache-dir install flaml[test,notebook]
+RUN pip3 --disable-pip-version-check --no-cache-dir install flaml[test,notebook]
+# For docs
+RUN npm install --global yarn
+RUN pip install pydoc-markdown

.github/workflows/deploy-website.yml

@@ -0,0 +1,88 @@
+name: docs
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  checks:
+    if: github.event_name != 'push'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 14.x
+          # cache: yarn
+          # cache-dependency-path: '**/yarn.lock'
+      - name: setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+      - name: pydoc-markdown install
+        run: |
+          python -m pip install --upgrade pip
+          pip install pydoc-markdown
+      - name: pydoc-markdown run
+        run: |
+          pydoc-markdown
+      - name: Test Build
+        run: |
+          if [ -e yarn.lock ]; then
+          yarn install --frozen-lockfile
+          yarn build
+          elif [ -e package-lock.json ]; then
+          npm ci
+          npm run build
+          else
+          npm i --legacy-peer-deps
+          npm run build
+          fi
+  gh-release:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 14.x
+          # cache: yarn
+          # cache-dependency-path: '**/yarn.lock'
+      - name: setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+      - name: pydoc-markdown install
+        run: |
+          python -m pip install --upgrade pip
+          pip install pydoc-markdown
+      - name: pydoc-markdown run
+        run: |
+          pydoc-markdown
+      - name: Build website
+        run: |
+          if [ -e yarn.lock ]; then
+          yarn install --frozen-lockfile
+          yarn build
+          elif [ -e package-lock.json ]; then
+          npm ci
+          npm run build
+          else
+          npm i --legacy-peer-deps
+          npm run build
+          fi
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./website/build

.github/workflows/python-package.yml

@@ -70,27 +70,27 @@ jobs:
           file: ./coverage.xml
           flags: unittests
 
-  docs:
+  # docs:
 
-    runs-on: ubuntu-latest
+  #   runs-on: ubuntu-latest
 
-    steps:
-      - uses: actions/checkout@v2
-      - name: Setup Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: '3.8'
-      - name: Compile documentation
-        run: |
-            pip install -e .
-            python -m pip install sphinx sphinx_rtd_theme
-            cd docs
-            make html
-      - name: Deploy to GitHub pages
-        if: ${{ github.ref == 'refs/heads/main' }}
-        uses: JamesIves/[email protected]
-        with:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          BRANCH: gh-pages
-          FOLDER: docs/_build/html
-          CLEAN: true
+  #   steps:
+  #     - uses: actions/checkout@v2
+  #     - name: Setup Python
+  #       uses: actions/setup-python@v2
+  #       with:
+  #         python-version: '3.8'
+  #     - name: Compile documentation
+  #       run: |
+  #           pip install -e .
+  #           python -m pip install sphinx sphinx_rtd_theme
+  #           cd docs
+  #           make html
+  #     - name: Deploy to GitHub pages
+  #       if: ${{ github.ref == 'refs/heads/main' }}
+  #       uses: JamesIves/[email protected]
+  #       with:
+  #         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  #         BRANCH: gh-pages
+  #         FOLDER: docs/_build/html
+  #         CLEAN: true

.gitignore

@@ -1,4 +1,4 @@
-# Project
+# Project
 /.vs
 .vscode
 

Dockerfile

@@ -1,7 +1,7 @@
 # basic setup
 FROM python:3.7
 RUN apt-get update && apt-get -y update
-RUN apt-get install -y sudo git
+RUN apt-get install -y sudo git npm
 
 # Setup user to not run as root
 RUN adduser --disabled-password --gecos '' flaml-dev
@@ -19,6 +19,12 @@ RUN sudo pip install -e .[test,notebook]
 # Install precommit hooks
 RUN pre-commit install
 
+# For docs
+RUN npm install --global yarn
+RUN pip install pydoc-markdown
+RUN cd website
+RUN yarn install --frozen-lockfile
+
 # override default image starting point
 CMD /bin/bash
 ENTRYPOINT []