📚 Quarto + Quaro Books for Documentation (#43)

## 📚 What?

This PR replaces {pkgdown} with Quarto books for package documentation.
The documentation renders on changes to its yaml-file or modification of
the /docs folder. It is still a work in progress, and needs some serious
polishing when the package is ready for CRAN submission.

---------

Signed-off-by: Serkan Korkmaz <[email protected]>

.github/workflows/build-docs.yml

@@ -0,0 +1,62 @@
+on:
+  workflow_dispatch:
+  push:
+    branches: [development, quarto-docs]
+    paths: ['docs/**', '.github/workflows/build-docs.yml']
+
+name: Build Docs
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      R_KEEP_PKG_SOURCE: yes
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          tinytex: true
+
+
+      - name: Install R
+        uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: 'release'
+
+      - name: Setup R dependencies
+        uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          cache: 'always'
+          packages:
+            local::.
+            deps::.
+          extra-packages:
+            any::MLmetrics
+            any::mlr3measures
+            any::yardstick
+            any::bench
+            any::tidyverse
+            any::tidymodels
+
+      - name: Render docs
+        uses: quarto-dev/quarto-actions/render@v2
+        with:
+          to: html 
+          path: docs/
+
+      - name: Publish docs
+        uses: quarto-dev/quarto-actions/publish@v2
+        with:
+          target: gh-pages
+          path: docs/
+          render: false
+

.gitignore

@@ -39,9 +39,6 @@ vignettes/*.pdf
 # R Environment Variables
 .Renviron
 
-# pkgdown site
-docs/
-
 # translation temp files
 po/*~
 
@@ -51,7 +48,6 @@ rsconnect/
 
 # sandbox
 sandbox/
-docs
 inst/doc
 
 
@@ -61,7 +57,8 @@ src/cmake-build-debug
 src/.idea
 
 /.quarto/
-
+docs/*/
 # html-files
 # (from rendering markdown/quarto)
 *.html
+/README_files

Makefile

@@ -42,8 +42,9 @@ build: document
 	@echo "✅ Done!"
 	@rm -f $(TARBALL)
 	@rm -f src/*.o src/*.so
-	@Rscript tools/render.R
-	$(MAKE) build-site
+	@quarto render README.qmd
+	@quarto render NEWS.qmd
+	$(MAKE) build-docs
 	@echo "✅ Build process done!"
 
 check: document
@@ -60,13 +61,12 @@ check: document
 	@rm -f $(TARBALL)
 	@rm -rf $(PKGNAME).Rcheck
 	@rm -f src/*.o src/*.so
-	@Rscript tools/render.R
+	@quarto render README.qmd
+	@quarto render NEWS.qmd
 	@echo "✅ R CMD check process done!"
 
-build-site:
-	@clear
-	@echo "📚 Building {pkgdown}"
-	@Rscript -e "pkgdown::build_site()"
-
-preview:
-	@xdg-open docs/index.html
+
+build-docs:
+	@echo "📚 Building Quarto Book"
+	@python3 tools/YAML.py
+	cd docs/ && quarto preview

NEWS.md

@@ -1,4 +1,5 @@
 
+
 # Version 0.3-1
 
 > Version 0.3-1 is considered pre-release of {SLmetrics}. We do not
@@ -7,10 +8,9 @@
 
 ## :rocket: Improvements
 
-- **OpenMP Support (PR
-  <https://github.com/serkor1/SLmetrics/pull/40>):** {SLmetrics} now
-  supports parallelization through OpenMP. The OpenMP can be utilized as
-  follows:
+- **OpenMP Support (PR https://github.com/serkor1/SLmetrics/pull/40):**
+  {SLmetrics} now supports parallelization through OpenMP. The OpenMP
+  can be utilized as follows:
 
 ``` r
 # 1) probability distribution
@@ -36,7 +36,7 @@ system.time(SLmetrics::entropy(pk))
 ```
 
     #>    user  system elapsed 
-    #>   0.053   0.002   0.004
+    #>   0.007   0.002   0.001
 
 ``` r
 # 3) Disable OpenMP
@@ -50,10 +50,10 @@ system.time(SLmetrics::entropy(pk))
 ```
 
     #>    user  system elapsed 
-    #>   0.001   0.000   0.001
+    #>   0.000   0.000   0.001
 
 - **Entropy with soft labels
-  (<https://github.com/serkor1/SLmetrics/issues/37>):** `entropy()`,
+  (https://github.com/serkor1/SLmetrics/issues/37):** `entropy()`,
   `cross.entropy()` and `relative.entropy()` have been introduced. These
   functions are heavily inspired by {scipy}. The functions can be used
   as follows:
@@ -77,14 +77,14 @@ qk <- matrix(
 # 2) calculate
 # Entropy
 cat(
-  "Entropy", entropy(
+  "Entropy", SLmetrics::entropy(
     pk
   ),
-  "Relative Entropy", relative.entropy(
+  "Relative Entropy", SLmetrics::relative.entropy(
     pk,
     qk
   ),
-  "Cross Entropy", cross.entropy(
+  "Cross Entropy", SLmetrics::cross.entropy(
     pk,
     qk
   ),
@@ -110,7 +110,7 @@ cat(
 ## :bug: Bug-fixes
 
 - **Plot-method in ROC and prROC
-  (<https://github.com/serkor1/SLmetrics/issues/36>):** Fixed a bug in
+  (https://github.com/serkor1/SLmetrics/issues/36):** Fixed a bug in
   `plot.ROC()` and `plot.prROC()` where if `panels = FALSE` additional
   lines would be added to the plot.
 
@@ -363,7 +363,7 @@ try(
 - **Floating precision:** Metrics would give different results based on
   the method used. This means that `foo.cmatrix()` and `foo.factor()`
   would produce different results (See Issue
-  <https://github.com/serkor1/SLmetrics/issues/16>). This has been fixed
+  https://github.com/serkor1/SLmetrics/issues/16). This has been fixed
   by using higher precision `Rcpp::NumericMatrix` instead of
   `Rcpp::IntegerMatrix`.
 
@@ -380,17 +380,17 @@ try(
 
 - **Calculation Error in Pinball Deviance and Concordance Correlation
   Coefficient:** See issue
-  <https://github.com/serkor1/SLmetrics/issues/19>. Switched to unbiased
+  https://github.com/serkor1/SLmetrics/issues/19. Switched to unbiased
   variance calculation in `ccc()`-function. The `pinball()`-function
   were missing a weighted quantile function. The issue is now fixed.
 
 - **Calculation Error in Balanced Accuracy:** See issue
-  <https://github.com/serkor1/SLmetrics/issues/24>. The function now
+  https://github.com/serkor1/SLmetrics/issues/24. The function now
   correctly adjusts for random chance, and the result matches that of
   {scikit-learn}
 
 - **Calculation Error in F-beta Score:** See issue
-  <https://github.com/serkor1/SLmetrics/issues/23>. The function werent
+  https://github.com/serkor1/SLmetrics/issues/23. The function werent
   respecting `na.rm` and `micro`, this has been fixed accordingly.
 
 - **Calculation Error in Relative Absolute Error:** The function was
@@ -468,7 +468,7 @@ SLmetrics::accuracy(
 
 - The `plot.prROC()`- and `plot.ROC()`-functions now adds a line to the
   plot when `panels = FALSE`. See Issue
-  <https://github.com/serkor1/SLmetrics/issues/9>.
+  https://github.com/serkor1/SLmetrics/issues/9.
 
 ``` r
 # 1) define actual
@@ -505,7 +505,7 @@ plot(
 )
 ```
 
-![](NEWS_files/figure-gfm/unnamed-chunk-12-1.png)<!-- -->
+![](NEWS_files/figure-commonmark/unnamed-chunk-12-1.png)
 
 ``` r
 plot(
@@ -514,7 +514,7 @@ plot(
 )
 ```
 
-![](NEWS_files/figure-gfm/unnamed-chunk-12-2.png)<!-- -->
+![](NEWS_files/figure-commonmark/unnamed-chunk-12-2.png)
 
 # Version 0.1-0
 

NEWS.Rmd → NEWS.qmd

@@ -1,7 +1,7 @@
 ---
-output:
-  github_document:
-    html_preview: false
+format: 
+    gfm:
+        default-image-extension: ""
 always_allow_html: true
 ---
 
@@ -167,7 +167,8 @@ cat(
 
 Prior to version `0.3-0` the weighted confusion matrix were a part of the `cmatrix()`-function and were called as follows,
 
-```{r, eval = FALSE}
+```{r}
+#| eval: false
 SLmetrics::cmatrix(
     actual    = actual,
     predicted = predicted,
@@ -312,7 +313,9 @@ SLmetrics::weighted.rmse(actual, predicted, w = w)
 
 * **NA-controls:** All pair-wise metrics that doesn't have a `micro`-argument were handling missing values as according to C++ and {Rcpp} internals. See [Issue](https://github.com/serkor1/SLmetrics/issues/8). Thank you @EmilHvitfeldt for pointing this out. This has now been fixed so functions uses an `na.rm`-argument to explicitly control for this. See below,
 
-```{r, eval = FALSE}
+```{r}
+#| eval: false
+
 # 1) define factors
 actual    <- factor(c("no", "yes"))
 predicted <- factor(c(NA, "no"))

README.md

@@ -1,4 +1,5 @@
 
+
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
 # {SLmetrics}: Machine learning performance evaluation on steroids <img src="man/figures/logo.png" align="right" height="150" alt="" />
@@ -157,7 +158,8 @@ RMSE[^1].
 
 ### :fast_forward: Speed comparison
 
-<img src="man/figures/README-performance-1.png" width="100%" />
+<img src="man/figures/README-unnamed-chunk-4-1.png"
+style="width:100.0%" />
 
 As shown in the chart,
 [{SLmetrics}](https://serkor1.github.io/SLmetrics/) maintains