docs(website): better display of "Usage" section (#626)

Co-authored-by: eitsupi <[email protected]>

.github/workflows/docs.yaml

@@ -11,12 +11,22 @@ on:
       - main
     tags:
       - "v*"
+    paths:
+      - .github/workflows/docs.yaml
+      - altdoc/**
+      - man/**
+      - R/**
+      - src/**
+      - vignetts/**
+      - DESCRIPTION
+      - README.md
   pull_request:
     branches:
       - main
     paths:
       - .github/workflows/docs.yaml
-      - docs/**
+      - altdoc/**
+      - man/**
       - R/**
       - src/**
       - vignetts/**

.gitignore

@@ -51,3 +51,5 @@ tools/libr_polars.a
 altdoc/freeze.rds
 docs
 .venv_altdoc
+altdoc/mkdocs.yml
+altdoc/reference_home.md

Makefile

@@ -66,7 +66,7 @@ all: fmt tools/lib-sums.tsv build test README.md LICENSE.note ## build -> test -
 
 .PHONY: docs
 docs: build install README.md altdoc/reference_home.md ## Generate docs
-	Rscript -e 'future::plan(future::multicore); source("altdoc/altdoc_preprocessing.R"); altdoc::render_docs(freeze = FALSE, parallel = TRUE, verbose = TRUE)'
+	Rscript -e 'future::plan(future::multicore); source("altdoc/altdoc_preprocessing.R"); altdoc::render_docs(freeze = FALSE, parallel = TRUE, verbose = TRUE);source("altdoc/altdoc_postprocessing.R")'
 
 .PHONY: docs-preview
 docs-preview: ## Preview docs on local server. Needs `make docs`

Taskfile.yml

@@ -238,19 +238,19 @@ tasks:
     sources:
       - man/*.Rd
       - altdoc/altdoc_preprocessing.R
+      - altdoc/altdoc_postprocessing.R
       - altdoc/*.yml
       - "{{.VIGNETTES}}"
     generates:
       - docs/**
-    deps:
-      - install-package
-      - build-readme
-      - build-altdoc-ref-home
     cmds:
+      - task: build-readme
+      - task: build-altdoc-ref-home
       - Rscript -e
         'future::plan(future::multicore);
         source("altdoc/altdoc_preprocessing.R");
-        altdoc::render_docs(freeze = FALSE, parallel = TRUE, verbose = TRUE)'
+        altdoc::render_docs(freeze = FALSE, parallel = TRUE, verbose = TRUE);
+        source("altdoc/altdoc_postprocessing.R");'
 
   build-altdoc-ref-home:
     internal: true
@@ -276,10 +276,10 @@ tasks:
     vars:
       FORMATER_SCRIPT: dev/styler_utils.R
     sources:
-      - "{{.R_SOURCE}}"
+      - "**/*.R"
       - "{{.FORMATER_SCRIPT}}"
     generates:
-      - "{{.R_SOURCE}}"
+      - "**/*.R"
       - exclude: R/extendr-wrappers.R
     cmds:
       - Rscript -e

altdoc/altdoc_postprocessing.R

@@ -0,0 +1,79 @@
+### To be run after altdoc::render_docs()
+
+list_man_html = list.files("docs/man",
+  pattern = "\\.html$", full.names = TRUE,
+  recursive = TRUE
+)
+
+### Make the "Usage" section prettier (if there is one):
+### DataFrame_describe(...)   ->   <DataFrame>$describe()
+
+classes = c(
+  "Series", "DataFrame", "LazyFrame", "GroupBy",
+  "LazyGroupBy", "IO", "RField", "RThreadHandle", "SQLContext", "S3",
+  "Expr"
+)
+
+to_modify = grep(
+  paste0("/", paste(classes, collapse = "|")),
+  list_man_html,
+  value = TRUE
+)
+
+for (i in to_modify) {
+  which_class = gsub("docs/man/([^_]+).*$", "\\1", i, perl = TRUE)
+  orig = readLines(i, warn = FALSE)
+
+  if (!any(grepl("<h2 id=\"usage\">Usage</h2>", orig))) {
+    next
+  }
+  new = gsub(
+    paste0("<code class='language-R'>", which_class, "_"),
+    paste0("<code class='language-R'>&lt;", which_class, "&gt;$"),
+    orig
+  )
+  writeLines(new, i)
+}
+
+
+### Add a "Usage" section if there is none (which is the case for all Expr)
+
+# Expr_classes = c("pl", "ExprList", "ExprBin", "ExprCat", "ExprDT", "ExprMeta",
+#                  "ExprName", "ExprStr", "ExprStruct")
+#
+# to_modify2 = grep(
+#   paste0("/", paste(Expr_classes, collapse = "|")),
+#   list_man_html,
+#   value = TRUE
+# )
+#
+# for (i in to_modify2) {
+#   which_class = gsub("docs/man/(.*)_.*$", "\\1", i)
+#   orig = readLines(i, warn = FALSE)
+#
+#   if (any(grepl("<h2 id=\"usage\">Usage</h2>", orig))) {
+#     next
+#   }
+#
+#   before_usage = grep("id=\"description\">", orig) + 1
+#   after_usage = grep("id=\"description\">", orig) + 2
+#   if (length(before_usage) == 0) {
+#     next
+#   }
+#
+#   usage = if (grep("^Expr", which_class)) {
+#     paste0("&lt;Expr&gt;$", tolower(gsub("^Expr", "", which_class)))
+#   } else if (which_class == "pl") {
+#     "pl"
+#   }
+#
+#   usage = paste0(usage, "$")
+#   new = c(
+#     orig[1:before_usage],
+#     "<h2 id=\"usage\">Usage</h2>",
+#     paste0("<pre><code class='language-R'>", usage),
+#     "</code></pre>",
+#     orig[after_usage:length(orig)]
+#   )
+#   writeLines(new, i)
+# }