docs: Add tutorials (#101)

* add tutorials
* improve the documentation configuration
* add a workflow dispatch for publishing documentation

.github/workflows/docs.yaml

@@ -0,0 +1,42 @@
+name: Documentation
+
+on:
+  workflow_dispatch:
+
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: conda-incubator/setup-miniconda@v3
+        with:
+          miniforge-version: latest
+          environment-file: conda/dev.yaml
+          channels: conda-forge,nodefaults
+          activate-environment: makim
+          auto-update-conda: true
+          conda-solver: libmamba
+
+      - name: Install deps
+        run: |
+          poetry config virtualenvs.create false
+          poetry install
+
+      - name: Generate documentation with changes from semantic-release
+        run: makim --verbose docs.build
+
+      - name: GitHub Pages action
+        uses: peaceiris/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build/

.makim.yaml

@@ -21,25 +21,6 @@ groups:
 
   docs:
     targets:
-      pre-build:
-        help: pre-build step
-        shell: bash
-        run: |
-          mkdir -p build
-          # Directory to search for .ipynb files
-          export SEARCH_DIR="docs/tutorials"
-
-          # Find all .ipynb files, excluding .ipynb_checkpoints,
-          # and convert them to Markdown named 'index.md'
-          find "$SEARCH_DIR" -path "*/.ipynb_checkpoints/*" -prune -o -name \
-            "*.ipynb" -exec sh -c \
-            'jupyter nbconvert --to markdown --output-dir "$(dirname "$0")" "$0"' {} \;
-
-          # remove console colors from md files
-          find "$SEARCH_DIR" -name \
-            "*.md" -exec sh -c \
-            'cat "$0" | python docs/scripts/clean-output.py > "$(dirname "$0")/temp_index.md" && mv "$(dirname "$0")/temp_index.md" "$0"' {} \;
-
       build:
         help: Build documentation
         run: |

docs/scripts/clean-output.py

@@ -0,0 +1,21 @@
+import re
+import sys
+
+def remove_ansi_escape_sequences(text: str) -> str:
+    """
+    Remove ANSI escape sequences from a string.
+
+    Parameters:
+    - text: A string that may contain ANSI escape codes.
+
+    Returns:
+    - A string with ANSI escape codes removed.
+    """
+    # ANSI escape code regex pattern
+    ansi_escape_pattern = re.compile(r'(?:\x1B[@-_]|[\x80-\x9F])[0-?]*[ -/]*[@-~]')
+    return ansi_escape_pattern.sub('', text)
+
+if __name__ == "__main__":
+    input_text = sys.stdin.read()
+    cleaned_text = remove_ansi_escape_sequences(input_text)
+    print("{% raw %}" + cleaned_text + "{% endraw %}", end='')

docs/tutorials/introduction/.makim.yaml

@@ -0,0 +1,12 @@
+version: 1.0
+working-directory: "/tmp"
+
+groups:
+  check-wd:
+    targets:
+      is-tmp:
+        help: Test if working directory is `tmp`
+        run: |
+          import os
+          print(os.getcwd())
+          assert os.getcwd() == "/tmp"