⚒️ Repo-tools, QoL and clean-up (#53)

## 📚 What?

This PR is (mostly) quality of life improvements to the repository, and
minor changes to the layout of `README` and `NEWS`

See PR #53

.github/actions/setup-reticulate/action.yml

@@ -25,30 +25,38 @@ runs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ inputs.python-version }}
+        cache: pip
+
+    - name: "Setup Python dependencies"
+      shell: bash
+      run: |
+       pip install -r tools/requirements.txt
 
     - name: Setup venv with {Reticulate}
       shell: Rscript {0}
       env:
         PYTHON_VERSION: ${{ inputs.python-version }}
       run: |
 
-        # 1) create virtual environment
+        # 1) define python modules
+        py_modules <- c(
+          "numpy",
+          "scipy",
+          "torch",
+          "torchmetrics",
+          "scikit-learn",
+          "imblearn"
+        )
+
+        # 2) create virtual environment
         # with specified version
-        
         path_to_python <- tryCatch(
           expr = {
 
             reticulate::virtualenv_create(
-              envname        = "r-reticulate",
-              python         =  Sys.which("python"),
-              packages = c(
-                "numpy",
-                "scipy",
-                "torch",
-                "torchmetrics",
-                "scikit-learn",
-                "imblearn"
-              )
+              envname  = "r-reticulate",
+              python   =  Sys.which("python"),
+              packages = py_modules
             )
           
           },
@@ -57,20 +65,13 @@ runs:
             reticulate::virtualenv_create(
               envname        = "r-reticulate",
               python_version =  Sys.getenv("PYTHON_VERSION"),
-              packages = c(
-                "numpy",
-                "scipy",
-                "torch",
-                "torchmetrics",
-                "scikit-learn",
-                "imblearn"
-              )
+              packages       = py_modules
             )
 
           }
         )
 
-        # 2) write path to
+        # 3) write path to
         # environment
         writeLines(
           sprintf("RETICULATE_PYTHON=%s", path_to_python),

.github/workflows/build-docs.yml

@@ -50,6 +50,26 @@ jobs:
             any::tidymodels
             any::stringi
 
+      - name: Setup Python 
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12.x'
+          cache: pip
+
+      - name: "Setup Python dependencies"
+        shell: bash
+        run: |
+          pip install -r tools/requirements.txt
+
+      - name: Build YAML-file
+        run: python tools/doc-builders/YAML.py
+
+      - name: Render docs
+        uses: quarto-dev/quarto-actions/render@v2
+        with:
+          to: html 
+          path: docs/
+
       - name: Parse Roxygen files
         shell: Rscript {0}
         run: |

.gitignore

@@ -50,19 +50,14 @@ rsconnect/
 sandbox/
 inst/doc
 
-
-# Clion Files
-src/CMakeLists.txt
-src/cmake-build-debug
-src/.idea
-
-/.quarto/
-docs/*/
-
 # html-files
 # (from rendering markdown/quarto)
 *.html
-/README_files
-/README_cache
-/NEWS_files
-/NEWS_cache
+
+
+# Ignore all subdirectories in meta/
+meta/*
+
+# Do not ignore NEWS_files and README_files within meta/
+!meta/NEWS_files/
+!meta/README_files/

Makefile

@@ -9,8 +9,76 @@ PKGNAME = SLmetrics
 VERSION = $(shell grep "^Version:" DESCRIPTION | sed "s/Version: //")
 TARBALL = $(PKGNAME)_$(VERSION).tar.gz
 
+# ---------- MAKE helpers ---------- #
+# build-meta
+#
+# This command renders README.qmd and NEWS.qmd and moves
+# them to root directory. 
+#
+# Because of stuff, the command now replaces all dirs with meta/dir... Otherwise images are
+# not rendered
+build-meta:
+	@echo "📚 Rendering README and NEWS"
+
+	@quarto render meta/README.qmd
+	@quarto render meta/NEWS.qmd
+
+	@mv meta/README.md .
+	@mv meta/NEWS.md .
+
+	@Rscript -e "file_path <- 'NEWS.md'; \
+	             file_contents <- readLines(file_path); \
+	             modified_contents <- gsub('NEWS_files/', 'meta/NEWS_files/', file_contents); \
+	             writeLines(modified_contents, file_path); \
+	             cat('Replacements completed in NEWS.md\\n')"
+
+	@Rscript -e "file_path <- 'README.md'; \
+	             file_contents <- readLines(file_path); \
+	             modified_contents <- gsub('README_files/', 'meta/README_files/', file_contents); \
+	             writeLines(modified_contents, file_path); \
+	             cat('Replacements completed in README.md\\n')"
+
+
+# preview-docs
+#
+# This command runs all builders in 
+# in tools for the online documentation.
+#
+# NOTE: Its primarily meant for debugging, as the documentation
+# is built via Github actions.
+preview-docs:
+	@echo "📚 Building Quarto Book"
+
+	@python3 tools/doc-builders/YAML.py
+	@Rscript -e "source('tools/doc-builders/build-qmd.R')"
+
+	@cd docs/ && quarto preview
+
+# document:
+#
+# This command runs all top-level scripts in
+# tools/
+#
+# document.R: This file recompiles the attributes in the .cpp-files, modifiess the RcppExports.R via
+# tools/modifyRcppExports.R and then runs roxygenize twice to build the documentation
+# with arguments like ellipsis and `na.rm`
+document:
+	@echo "📚 Documenting {$(PKGNAME)}"
+
+	@Rscript tools/document.R
+
+# ---------- MAKE commands ---------- #
+# performance:
+# 
+# This command runs all scripts in data-raw
+# individually and stores them in sysdata.rd
+#
+# NOTE: The command overwrites the file, so it will have to 
+# be run to finish.
+# 
+# The scripts can be run individually if only parts of the
+# performance tests are needed to be re-run.
 performance:
-	@clear
 	@echo "🚀 Running performance-tests in {${PKGNAME}}"
 	@echo "==========================================="
 	@Rscript -e "DT <- list(); usethis::use_data(DT, internal = TRUE, overwrite = TRUE)" > /dev/null 2>&1
@@ -25,50 +93,72 @@ performance:
 	@echo "✅ All performance tests completed successfully!"
 	@echo "⚠️ Remember to rebuild {${PKGNAME}} to use the new data!"
 
-document:
-	@clear
-	@echo "📚 Documenting {$(PKGNAME)}"
-	@quarto render README.qmd
-	@quarto render NEWS.qmd
-	@Rscript tools/document.R
-
+# build:
+#
+# This command is runs R CMD build ., R CMD INSTALL .
+# which builds and installs {SLmetrics}.
+#
+# When the process is done it will clean up
+# the repository by executing the clean command, and rebuild 
+# the README and NEWS
+#
+# Call it with buld CHECK=true if the package needs to
+# be checked before install. Or run the check-wrapper
+#
+# NOTE: If the check fails, it will not install.
 build: document
 	@echo "▶️ Starting build process of {$(PKGNAME)}"
 	@echo "⚒️ Building {$(PKGNAME)} ..."
-	@rm -f src/*.o src/*.so
+	@echo ""
+
 	@R CMD build . > /dev/null 2>&1
 	@echo "✅ Done!"
+	@echo ""
+
+	@if [ "$(CHECK)" = "true" ]; then \
+		echo "🔎 Checking {$(PKGNAME)} ..."; \
+		R CMD check --no-manual --as-cran $(TARBALL); \
+			echo "🗑️ Cleaning branches"; \
+	fi
+
 	@echo "⚒️ Installing {$(PKGNAME)} ..."
 	@R CMD INSTALL $(TARBALL) > /dev/null 2>&1
 	@echo "✅ Done!"
-	@rm -f $(TARBALL)
-	@rm -f src/*.o src/*.so
-	@quarto render README.qmd
-	@quarto render NEWS.qmd
-	$(MAKE) build-docs
+	@echo ""
+
+
+	$(MAKE) clean BRANCH=false
+	$(MAKE) build-meta
 	@echo "✅ Build process done!"
 
-check: document
-	@echo "▶️ Starting R CMD check process of {$(PKGNAME)}"
-	@rm -f src/*.o src/*.so
-	@echo "⚒️ Building {$(PKGNAME)} ..."
-	@R CMD build . > /dev/null 2>&1
-	@echo "✅ Done!"
-	@echo "🔎 Checking {$(PKGNAME)} ..."
-	@R CMD check --no-manual --as-cran $(TARBALL)
-	@echo "⚒️ Installing {$(PKGNAME)} ..."
-	@R CMD INSTALL $(TARBALL) > /dev/null 2>&1
-	@echo "✅ Done!"
-	@rm -f $(TARBALL)
-	@rm -rf $(PKGNAME).Rcheck
-	@rm -f src/*.o src/*.so
-	@quarto render README.qmd
-	@quarto render NEWS.qmd
-	@echo "✅ R CMD check process done!"
+# check:
+#
+# This command is a wrapper of 
+# build with CHECK=true
+check:
+	$(MAKE) build CHECK=true
 
+# clean:
+#
+# This command performs a clean
+# up of the repository. It conditionally deletes branches, and deletes
+# README.md, NEWS.md and all build files.S
+#
+# Use make clean BRANCH=true to delete all branches
+# excecpt main and development.
+clean:
+	@echo "🗑️ Cleaning reposiory"
+	@echo ""
 
-build-docs:
-	@echo "📚 Building Quarto Book"
-	@python3 tools/YAML.py
-	@Rscript -e "source('tools/doc-builders/build-qmd.R')"
-	@cd docs/ && quarto preview
+	@if [ "$(BRANCH)" = "true" ]; then \
+		echo "🗑️ Cleaning branches"; \
+		git branch | grep -v "main" | grep -v "development" | xargs git branch -D; \
+	fi
+
+	# clean-up meta
+	@rm NEWS.md
+	@rm README.md
+
+	# clean-up build-files
+	@rm -f src/*.o src/*.so
+	@rm -f $(TARBALL)