docs: setup new docs with mkdocs (#1418)

.github/workflows/docs.yaml

@@ -0,0 +1,84 @@
+name: Publish Documentation
+
+
+
+on:
+  push:
+    paths:
+    - .github/workflows/docs.yaml
+    - docs/**
+    - examples/**
+    - mkdocs.yml
+    - requirements-docs.txt
+    branches:
+    - main
+  release:
+    types:
+    - released
+
+
+
+jobs:
+  prepare:
+    name: Get Current version
+    runs-on: ubuntu-22.04
+
+    outputs:
+      version: ${{ steps.version.outputs.value }}
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        token: ${{ secrets.ACCESS_TOKEN }}
+
+    - name: Find Latest Tag
+      id: latest_tag
+      uses: oprypin/[email protected]
+      with:
+        repository: ${{ github.repository }}
+        regex: '^v\d+\.\d+\.\d+$'
+
+    - name: Extract major and minor version
+      id: version
+      run: |
+        echo "value=`echo ${{ steps.latest_tag.outputs.tag }} | sed -r 's|v([0-9]+.[0-9]+).*|\1|g'`" >> $GITHUB_OUTPUT
+
+
+  publish-docs:
+    name: Publish Docs
+    runs-on: ubuntu-22.04
+
+    needs:
+    - prepare
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+        token: ${{ secrets.ACCESS_TOKEN }}
+
+    - name: Configurating Git
+      run: |
+        git config user.email "[email protected]"
+        git config user.name "Azory YData Bot"
+        git config core.autocrlf false
+
+    - name: Setup Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.10"
+
+    - name: Cache pip dependencies
+      id: cache
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+
+    - name: Install doc dependencies
+      run: |
+        python -m pip install --upgrade pip
+        make install-docs
+
+    - name: Publish
+      run: make publish-docs version=${{ needs.prepare.outputs.version }}

.github/workflows/merge-master.yml

@@ -41,71 +41,6 @@ jobs:
       run: echo "value=${{ steps.semantic.outputs.new_release_version }}.rc${{ steps.build_number.outputs.value }}" >> $GITHUB_OUTPUT
 
 
-  docs-changelog:
-    if: needs.prepare.outputs.new_release == 'true'
-    name: Update changelog on docs 
-    runs-on: ubuntu-22.04
-
-    needs: prepare
-
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-        token: ${{ secrets.ACCESS_TOKEN }}
-
-    - name: Calculate changelog path
-      id: path
-      run: echo "value=$(echo "${{ needs.prepare.outputs.release }}" | sed "s/\./_/g").md" >> $GITHUB_OUTPUT
-
-    - name: Configure Git
-      run: |
-        git config user.email "[email protected]"
-        git config user.name "Azory YData Bot"
-        git config core.autocrlf false
-
-    - name: Write changelog to file
-      uses: DamianReeves/write-file-action@master
-      with:
-        path: docsrc/source/pages/reference/changelog/${{ steps.path.outputs.value }}
-        contents: ${{ needs.prepare.outputs.release_notes }}
-        write-mode: overwrite
-
-    - name: Add changelog to docs
-      run: |
-        cd docsrc/source/pages/reference
-        sed -i -e 's/## \[.*/### Changelog ${{ needs.prepare.outputs.release }}/g' \
-            -e 's/### Bug Fixes/#### 🐛 Bug fixes/g' \
-            -e 's/### Features/#### 🎉 Features/g' \
-            -e 's/### BREAKING CHANGES/#### 🚨 Breaking changes/g' \
-            -e 's/### Documentation/#### 📖 Documentation/g' \
-            changelog/${{ steps.path.outputs.value }}
-
-        grep -q ".. include:: changelog/${{ steps.path.outputs.value }}" changelog.rst || sed -i "4 a\\
-        .. include:: changelog\/${{ steps.path.outputs.value }}\\
-           :parser: myst_parser.sphinx_\\
-
-        " changelog.rst
-
-    - name: Commit changelog
-      id: commit
-      run: |
-        if [[ `git status --porcelain` ]]; then
-          echo "CHANGES=true" >> $GITHUB_OUTPUT
-          git add docsrc/source/pages/reference/changelog/${{ steps.path.outputs.value  }}
-          git commit -m "[skip ci] Update changelogs" -a
-        else
-          echo "CHANGES=false" >> $GITHUB_OUTPUT
-        fi
-
-    - name: Push changes
-      uses: ad-m/[email protected]
-      if: ${{ steps.commit.outputs.CHANGES == 'true' }}
-      with:
-        branch: ${{ github.ref }}
-        github_token: ${{ secrets.ACCESS_TOKEN }}
-
-
   prerelease-tag:
     if: needs.prepare.outputs.new_release == 'true'
 
@@ -132,7 +67,6 @@ jobs:
 
     needs:
     - prepare
-    - docs-changelog
 
     steps:
     - name: Delete Previous drafts

.github/workflows/pull-request.yml

@@ -1,6 +1,5 @@
 name: Pull Request
 
-
 on:
   push:
     branches:
@@ -18,7 +17,7 @@ jobs:
         fetch-depth: 0
 
     - uses: wagoid/commitlint-github-action@v5
-    
+
   lint:
     if: github.actor != 'renovate[bot]'
     name: Lint source code
@@ -40,7 +39,7 @@ jobs:
     - name: Set up Python 3.8
       uses: actions/setup-python@v4
       with:
-        python-version: 3.8
+        python-version: "3.10"
 
     - uses: actions/cache@v3
       name: Cache pip dependencies
@@ -81,3 +80,36 @@ jobs:
       with:
         branch: ${{ github.head_ref }}
         github_token: ${{ secrets.ACCESS_TOKEN }}
+
+  validate-docs:
+    name: Validate Docs
+    runs-on: ubuntu-22.04
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Setup Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.10"
+
+    - name: Cache pip dependencies
+      id: cache
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -r requirements.txt
+        python -m pip install -r requirements-dev.txt
+        python -m pip install -r requirements-test.txt
+        python -m pip install -r requirements-docs.txt
+      
+    - name: Install the package
+      run: make install
+
+    - name: Build docs
+      run: mkdocs build

.github/workflows/release.yml

@@ -4,7 +4,7 @@ name: Release
 on:
   release:
     types:
-      - released
+    - released
 
 
 jobs:
@@ -19,10 +19,10 @@ jobs:
       id: version
       run: echo "value=${GITHUB_REF#refs/*/}" >> $GITHUB_OUTPUT
 
-    - name: Setup Python 3.8
+    - name: Setup Python 3.10
       uses: actions/setup-python@v4
       with:
-        python-version: "3.8"
+        python-version: "3.10"
 
     - uses: actions/cache@v3
       name: Cache pip dependencies
@@ -89,67 +89,3 @@ jobs:
       with:
         user: __token__
         password: ${{ secrets.PYPI_API_TOKEN }}
-
-  docs_and_examples:
-    name: Documentation and Examples
-    runs-on: ubuntu-22.04
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Configurating Git
-      run: |
-        git config user.email "[email protected]"
-        git config user.name "Azory YData Bot"
-        git config core.autocrlf false
-
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v4
-      with:
-        python-version: 3.8
-
-    - name: Install pip dependencies
-      run: |
-        pip install --upgrade pip
-        pip install -r requirements.txt
-        pip install -r requirements-dev.txt
-        pip install -r requirements-test.txt
-
-    - name: Install the package
-      run: |
-        make install
-
-    - name: Update examples
-      run: make examples
-
-    - name: Build the documentation
-      run: make docs
-
-    - name: Move the changes to the gh-pages branch (release branch)
-      run: |
-        mv docs master
-        mkdir docs
-        mv master docs/master
-        mv examples/ master
-        mkdir examples
-        mv master examples/master
-        git add -f docs/master
-        git add -f examples/master
-        git stash push -- docs/master examples/master
-        git fetch origin gh-pages
-        git checkout -f gh-pages
-        touch .nojekyll
-        git add .nojekyll
-        rm -rf docs/master
-        rm -rf examples/master
-        git add docs/
-        git add examples/
-        git stash apply
-        git commit -m "[skip ci] Updating documentation and examples" -a || true
-
-    - name: Push changes
-      uses: ad-m/github-push-action@master
-      with:
-        branch: gh-pages
-        directory: .
-        github_token: ${{ secrets.ACCESS_TOKEN }}

.gitignore

@@ -8,6 +8,7 @@ __pycache__/
 
 # Distribution / packaging
 .Python
+.venv
 env/
 build/
 develop-eggs/
@@ -77,7 +78,7 @@ playground/
 # build data
 examples/*/*.html
 examples/*/*.csv
-docs/
+static/docs
 docsrc/_build/
 docsrc/source/pages/api/_autosummary/
 

Makefile

@@ -1,10 +1,7 @@
 .PHONY: docs examples
 
 docs:
-	rm -rf docs/
-	mkdir docs/
-	# sphinx
-	cd docsrc/ && make github
+	mkdocs build
 
 test:
 	pytest tests/unit/
@@ -34,13 +31,21 @@ package:
 install:
 	pip install -e .[notebook]
 
+install-docs: install ### Installs regular and docs dependencies
+	pip install -r requirements-docs.txt
+
 install-spark-ci:
 	sudo apt-get update
 	sudo apt-get -y install openjdk-8-jdk
 	curl https://archive.apache.org/dist/spark/spark-${SPARK_VERSION}/spark-${SPARK_VERSION}-bin-hadoop${HADOOP_VERSION}.tgz \
 	--output ${SPARK_DIRECTORY}/spark.tgz
 	cd ${SPARK_DIRECTORY} && tar -xvzf spark.tgz && mv spark-${SPARK_VERSION}-bin-hadoop${HADOOP_VERSION} spark
 
+publish-docs: examples ### Publishes the documentation
+	mkdir docs/examples
+	rsync -R examples/*/*.html docs
+	mike deploy --push --update-aliases $(version) latest
+
 lint:
 	pre-commit run --all-files
 

docs/README.md

@@ -0,0 +1,16 @@
+# YData Profiling Documentation
+
+Installing the documentation dependencies (one time step):
+```bash
+make install-docs
+```
+
+Build the doc for deployment:
+```
+mkdocs build
+```
+
+To build and serve locally:
+```
+mkdocs serve
+```