Merge branch 'main' of https://github.com/IAS-Uni-Siegen/PE_course

Author: wallscheid

.gitattributes

@@ -0,0 +1,29 @@
+# Auto detect text files and normalize to LF on checkin
+* text=auto eol=lf
+
+# LaTeX files should always use LF line endings
+*.tex text eol=lf
+*.sty text eol=lf
+*.cls text eol=lf
+*.bib text eol=lf
+
+# Python files should always use LF line endings  
+*.py text eol=lf
+*.ipynb text eol=lf
+
+# YAML files should always use LF line endings
+*.yml text eol=lf
+*.yaml text eol=lf
+
+# Markdown files should always use LF line endings
+*.md text eol=lf
+
+# Binary files
+*.pdf binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.zip binary
+*.gz binary

.github/workflows/buildPDFs.yml

@@ -1,12 +1,109 @@
-name: Build LaTeX PDFs
+name: LaTeX + Python Check
 on: 
-  push: 
+  pull_request:
+    branches:
+      - main
     paths:
-        - '**.tex'
+      - '**.tex'
+      - '**.sty'
+      - '**.cls'
+      - '**.py'
+      - '**.ipynb'
+      - '**.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - '**.tex'
+      - '**.sty'
+      - '**.cls'
+      - '**.py'
+      - '**.ipynb'
+      - '**.yml'
   workflow_dispatch:
 
 jobs:
+  format-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Git repository
+        uses: actions/checkout@v4
+      
+      - name: Initialize and update submodules
+        run: |
+          git submodule init
+          git submodule update
+      
+      - name: Install latexindent binary
+        run: |
+          set -e
+
+          curl -L -o latexindent-linux \
+            https://github.com/cmhughes/latexindent.pl/releases/latest/download/latexindent-linux
+          chmod +x latexindent-linux
+          sudo mv latexindent-linux /usr/local/bin/latexindent
+          echo "latexindent installed at:"
+          which latexindent || echo "latexindent not found on PATH"
+
+          echo "latexindent verbose version info:"
+          latexindent -vv
+
+      - name: Check LaTeX formatting with latexindent (dry-run)
+        run: |
+          set -e
+          tmp_file="tmp_check_file"
+          for ext in tex sty cls; do
+            find . -name "*.${ext}" -type f -not -name "$tmp_file" | while read -r file; do
+              latexindent -m -l=./course_template/.latexindent.yml -o="$tmp_file" "$file"
+              if ! diff -qZb "$file" "$tmp_file.${ext}" > /dev/null; then
+                echo "::error file=$file::File is not properly formatted. Please run latexindent locally."
+                rm -f "$tmp_file.${ext}"
+                exit 1
+              fi
+              rm -f "$tmp_file.${ext}"
+            done || exit 1
+          done
+          echo "All LaTeX files are properly formatted!"
+      
+      - name: Install Python format tools
+        run: |
+          set -e
+          python -m pip install --upgrade pip
+          pip install ruff
+
+      - name: Check Python + Notebook formatting (Ruff)
+        run: |
+          set -e
+
+          echo "Checking .py files formatting..."
+          PY_FAILED=0
+          for file in $(find . -name "*.py" -not -path "*/.*"); do
+            if ! ruff format --check --config ./course_template/pyproject.toml "$file"; then
+              echo "::error file=$file::Formatting check failed for $file."
+              PY_FAILED=1
+            fi
+          done
+
+          echo "Checking .ipynb files formatting..."
+          NB_FAILED=0
+          for file in $(find . -name "*.ipynb" -not -path "*/.*"); do
+            if ! ruff format --check --config ./course_template/pyproject.toml "$file"; then
+              echo "::error file=$file::Formatting check failed for $file."
+              echo "TIP: There is likely a trailing newline at the end of a code cell."
+              ruff format --diff --config ./course_template/pyproject.toml "$file"
+              NB_FAILED=1
+            fi
+          done
+
+          if [ $PY_FAILED -ne 0 ] || [ $NB_FAILED -ne 0 ]; then
+            echo "Formatting check failed. You can check by running 'ruff format .' locally."
+            exit 1
+          fi
+          
+          echo "All files passed formatting!"
+
   build_latex:
+    needs: format-check
     runs-on: ubuntu-latest
     steps:
       - name: Set up Git repository
@@ -45,6 +142,7 @@ jobs:
 
   deploy:
     needs: build_latex
+    if: ${{ github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
 
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
     permissions:

.gitignore

@@ -321,4 +321,4 @@ simulations/*/*backups*
 *.ist
 *.equ
 *.eqn
-*.vscode
+*.ruff_cache

.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+    "recommendations": [
+        "James-Yu.latex-workshop",
+        "charliermarsh.ruff"
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+    "latex-workshop.formatting.latexindent.path": "latexindent",
+    "latex-workshop.formatting.latexindent.args": [
+        "-m",
+        "-l=%WORKSPACE_FOLDER%/course_template/.latexindent.yml",
+        "%TMPFILE%",
+        "-o=%TMPFILE%"
+    ],
+    "editor.formatOnSave": true,
+    "latex-workshop.formatting.latex": "latexindent",
+    "ruff.configuration": "./course_template/pyproject.toml",
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "explicit"
+        },
+        "editor.defaultFormatter": "charliermarsh.ruff"
+    },
+    "notebook.formatOnSave.enabled": true,
+    "notebook.codeActionsOnSave": {
+        "notebook.source.organizeImports": "explicit"
+    }
+}

README.md

@@ -58,4 +58,12 @@ The covered topics are:
 
 ![simulation buck converter](https://github.com/user-attachments/assets/2f699cac-79b3-4c94-8332-6910e940948d)
 
+# Contributing
 
+- We recommend using [VSCode](https://code.visualstudio.com/) as code editor.
+- [Ruff](https://github.com/astral-sh/ruff) should be installed.
+
+    ```bash
+    pip install ruff
+    ```
+- It is expected that [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) and [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) extensions are installed so that formatting of the code is achieved automatically.

course_template

@@ -1,84 +1,99 @@
-import os
 import fileinput
+import os
 from subprocess import call
 
-call_pdflatex_l = ['pdflatex', '-synctex=1',
-                   '-interaction=nonstopmode', 'main.tex']
+call_pdflatex_l = ["pdflatex", "-synctex=1", "-interaction=nonstopmode", "main.tex"]
+
 
 def clear_tex_binaries():
     # Clean up auxiliary LaTeX files
-    for file in os.listdir('.'):
-        if file.startswith('main'):
-            if not file.endswith(('.tex', '.pdf')):
+    for file in os.listdir("."):
+        if file.startswith("main"):
+            if not file.endswith((".tex", ".pdf")):
                 os.remove(file)
 
+
 def build_pdf(with_solution):
     # Modify and build the main.tex file
     clear_tex_binaries()
 
     # Flag to ensure documentclass line is modified correctly
     docclass_modified = False
-    
-    with fileinput.input('main.tex', inplace=True) as f:
+
+    with fileinput.input("main.tex", inplace=True) as f:
         for line in f:
-            if 'includeonly{' in line:
+            if "includeonly{" in line:
                 # Comment out the includeonly flag
-                print(f'%{line}', end='')
+                print(f"%{line}", end="")
             # Look for the documentclass line
-            elif '\\documentclass' in line and 'examClass' in line:
+            elif "\\documentclass" in line and "examClass" in line:
                 docclass_modified = True  # Set the flag that we have modified the line
 
                 # Split documentclass into its components
-                preamble, class_info = line.split('{', 1)
-                class_name = class_info.rstrip('}\n')  # Remove the trailing }
-                
+                preamble, class_info = line.split("{", 1)
+                class_name = class_info.rstrip("}\n")  # Remove the trailing }
+
                 if with_solution:
                     # Add the [solution] option if not present
-                    if '[' not in preamble:
-                        preamble = preamble.replace('\\documentclass', '\\documentclass[solution]')
+                    if "[" not in preamble:
+                        preamble = preamble.replace(
+                            "\\documentclass", "\\documentclass[solution]"
+                        )
                     else:
-                        preamble = preamble.replace('[', '[solution, ')
+                        preamble = preamble.replace("[", "[solution, ")
                 else:
                     # Remove the [solution] option if present
-                    preamble = preamble.replace('[solution, ', '[').replace('[solution]', '')
+                    preamble = preamble.replace("[solution, ", "[").replace(
+                        "[solution]", ""
+                    )
 
                 # Reassemble the documentclass line
-                print(f'{preamble}{{{class_name}}}', end='\n')
+                print(f"{preamble}{{{class_name}}}", end="\n")
             else:
-                print(line, end='')
-    
+                print(line, end="")
+
     # If we didn't modify the documentclass, raise an exception for debugging
     if not docclass_modified:
-        raise ValueError("documentclass line with 'examClass' not found or not modified.")
+        raise ValueError(
+            "documentclass line with 'examClass' not found or not modified."
+        )
 
     # Run pdflatex twice for proper compilation
     call(call_pdflatex_l)
     call(call_pdflatex_l)
 
+
 def process_directory(dir_path):
     os.chdir(dir_path)
-    
+
     # Check if main.tex exists
-    if not os.path.exists('main.tex'):
-        os.chdir('..')  # Go back to the parent directory if no main.tex
+    if not os.path.exists("main.tex"):
+        os.chdir("..")  # Go back to the parent directory if no main.tex
         return
-    
+
     # Build with solutions
     build_pdf(with_solution=True)
-    os.makedirs('../built', exist_ok=True)
-    os.replace('main.pdf', os.path.join('../../built', f'{os.path.basename(dir_path)}_with_solution.pdf'))
-    
+    os.makedirs("../built", exist_ok=True)
+    os.replace(
+        "main.pdf",
+        os.path.join("../../built", f"{os.path.basename(dir_path)}_with_solution.pdf"),
+    )
+
     # Build without solutions
     build_pdf(with_solution=False)
-    os.replace('main.pdf', os.path.join('../../built', f'{os.path.basename(dir_path)}.pdf'))
-    
-    os.chdir('..')
+    os.replace(
+        "main.pdf", os.path.join("../../built", f"{os.path.basename(dir_path)}.pdf")
+    )
+
+    os.chdir("..")
+
 
 def traverse_and_build(root_dir):
     for subdir, _, _ in os.walk(root_dir):
-        if os.path.exists(os.path.join(subdir, 'main.tex')):
+        if os.path.exists(os.path.join(subdir, "main.tex")):
             process_directory(subdir)
 
+
 if __name__ == "__main__":
     # Start the traversal from the current directory
     root_directory = os.getcwd()  # You can also specify a different directory if needed