Merge pull request #31 from CCBR/template-params

refactor: simplify module quarto template with params
CCBR · Oct 26, 2023 · acddd73 · acddd73
2 parents ac9cc6b + e140283
commit acddd73
Show file tree

Hide file tree

Showing 6 changed files with 66 additions and 65 deletions.
diff --git a/_quarto.yml b/_quarto.yml
@@ -1,12 +1,10 @@
 project:
   type: website
-  render: # don't render docs/templates
-    - "docs/*.qmd"
-    - "docs/modules/*.qmd"
-    - "docs/subworkflows/*.qmd"
-    - "README.md"
-    - "CHANGELOG.md"
+  render:
+    - "**.qmd"
+    - "**.md"
     - ".github/CONTRIBUTING.md"
+    - "!docs/templates/"
 
 website:
   title: "nf-modules"

diff --git a/docs/create-listings.py b/docs/create-listings.py
@@ -5,6 +5,7 @@
 from ruamel.yaml import YAML
 
 yaml = YAML(typ="rt")
+yaml_str = YAML(typ=["rt", "string"])
 
 
 def main():
@@ -19,33 +20,36 @@ def main():
 def write_listing_components(mtype):
     with open(f"docs/templates/modules.qmd", "r") as infile:
         template = infile.read()
-    listing = [
-        write_qmd(meta, template, mtype=mtype)
-        for meta in get_yaml_globs(f"{mtype}/**/meta.yml")
-    ]
-    write_yaml_object(listing, f"docs/{mtype}/{mtype}.yml")
+    for nf_meta in get_yaml_globs(f"{mtype}/**/meta.yml"):
+        write_qmd(nf_meta, template, mtype=mtype)
 
 
-def write_qmd(meta, template, mtype="modules"):
-    out_yml = f"docs/{mtype}/{meta['name']}.yml"
-    with open(out_yml, "w") as outfile:
-        yaml.dump(meta, outfile)
-    qmd = template.format(
-        title=meta["name"],
-        subtitle=meta["description"],
-        yaml_file=out_yml,
-        module_name="/".join(meta["name"].split("_")),
-        module_type=mtype,
-        module_path=meta["filename"].rstrip("meta.yml"),
-    )
-    out_qmd = f"docs/{mtype}/{meta['name']}.qmd"
-    with open(out_qmd, "w") as outfile:
-        outfile.write(qmd)
-    meta["title"] = meta.pop("name")
-    meta["subtitle"] = meta.pop("description")
-    meta["categories"] = meta.pop("keywords")
-    meta["path"] = f"/docs/{mtype}/{meta['title']}.qmd"
-    return meta
+def write_qmd(nf_meta, template, mtype="modules"):
+    # write out nextflow module meta.yml as-is
+    out_nf_yml = f"docs/{mtype}/{nf_meta['name']}.yml"
+    with open(out_nf_yml, "w") as outfile:
+        yaml.dump(nf_meta, outfile)
+
+    # create metadata for quarto file & listing
+    qmd_dict = {
+        "title": nf_meta["name"],
+        "subtitle": nf_meta["description"],
+        "categories": nf_meta["keywords"],
+        "params": {
+            "nf_yaml_file": out_nf_yml,
+            "module_name": "/".join(nf_meta["name"].split("_")),
+            "module_type": mtype,
+            "module_path": nf_meta["filename"].rstrip("meta.yml"),
+        },
+    }
+    extra_meta = "\n" + yaml_str.dump_to_string(qmd_dict)
+
+    # generate quarto file from template
+    template_split = template.split("---")
+    template_split[1] = "\n".join([extra_meta, template_split[1]])
+    qmd_str = "---".join(template_split)
+    with open(f"docs/{mtype}/{nf_meta['name']}.qmd", "w") as outfile:
+        outfile.write(qmd_str)
 
 
 def get_yaml_globs(infileglob):

diff --git a/docs/modules.qmd b/docs/modules.qmd
@@ -4,7 +4,7 @@ title-block-banner: true
 page-layout: full
 listing:
   - id: modules
-    contents: modules/modules.yml
+    contents: modules/
     type: grid
     fields: [title, subtitle, categories]
     sort-ui: false

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1 +1,2 @@
 ruamel.yaml
+ruamel.yaml.string
diff --git a/docs/subworkflows.qmd b/docs/subworkflows.qmd
@@ -4,7 +4,7 @@ title-block-banner: true
 page-layout: full
 listing:
   - id: subworkflows
-    contents: subworkflows/subworkflows.yml
+    contents: subworkflows/
     type: grid
     fields: [title, subtitle, categories]
     sort-ui: false

diff --git a/docs/templates/modules.qmd b/docs/templates/modules.qmd
@@ -1,83 +1,81 @@
 ---
-title: "{title}"
-subtitle: "{subtitle}"
 execute:
-    echo: false
+  echo: false
 engine: knitr
 ---
 
-<!-- This file is generated automatically from a template: docs/templates/modules.qmd-->
+<!-- This file is generated automatically from a template (docs/templates/modules.qmd) by docs/create-listings.py -->
 
-```{{r deps}}
+```{r deps}
 #| message: false
 library(dplyr)
 library(glue)
 library(here)
 library(knitr)
 library(tidyr)
 library(yaml)
-meta <- yaml::read_yaml(here("{yaml_file}"))
-yaml_to_df <- function(y) {{
+meta <- yaml::read_yaml(here(params$nf_yaml_file))
+yaml_to_df <- function(y) {
   dat <- as.data.frame(y) %>% t() %>% as.data.frame()
   dat['names'] <- rownames(dat)
   dat <- as_tibble(dat)
   dat %>%
     separate_wider_delim(names, '.', names = c('name', 'value')) %>%
     pivot_wider(names_from = value, values_from = V1)
-}}
+}
 ```
 
 ```sh
-nf-core {module_type} \
+nf-core `r params$module_type` \
   --git-remote https://github.com/CCBR/nf-modules \
-  install {module_name}
+  install `r params$module_name`
 ```
 
-[{{{{< fa brands github >}}}}  https://github.com/CCBR/nf-modules/tree/main/{module_path}](https://github.com/CCBR/nf-modules/tree/main/{module_path})
+[{{< fa brands github >}}  https://github.com/CCBR/nf-modules/.../`r params$module_path`](https://github.com/CCBR/nf-modules/tree/main/`r params$module_path`)
 
 
-## {{{{< fa arrow-right-to-bracket >}}}} Input
+## {{< fa arrow-right-to-bracket >}} Input
 
-```{{r input}}
+```{r input}
 #| message: false
 meta$input %>% yaml_to_df() %>% kable()
 ```
 
-## {{{{< fa arrow-right-from-bracket >}}}} Output
+## {{< fa arrow-right-from-bracket >}} Output
 
-```{{r output}}
+```{r output}
 #| message: false
 meta$output %>% yaml_to_df() %>% kable()
 ```
 
-```{{r tools-markdown}}
+```{r tools-markdown}
 #| output: asis
-home_symbol  <- '{{{{< fa solid globe >}}}}'
-book_symbol  <- '{{{{< fa solid book >}}}}'
-code_symbol <- '{{{{< fa regular file-code >}}}}'
+home_symbol  <- '{{< fa solid globe >}}'
+book_symbol  <- '{{< fa solid book >}}'
+code_symbol <- '{{< fa regular file-code >}}'
 
-if ('tools' %in% names(meta)) {{
+if ('tools' %in% names(meta)) {
     tools_df <- meta$tools %>% yaml_to_df()
-    for (colname in c('tool_dev_url', 'homepage', 'documentation')) {{
-        if (!(colname %in% colnames(tools_df))) {{
+    for (colname in c('tool_dev_url', 'homepage', 'documentation')) {
+        if (!(colname %in% colnames(tools_df))) {
             tools_df[colname] <- NA_character_
-        }}
-    }}
+        }
+    }
     markdown <- tools_df %>%
-      mutate(name = glue("### {{ name }}"),
-             home = case_when(!is.na(homepage) ~ glue("[{{ home_symbol }} Home]({{ homepage }})"),
+      mutate(name = glue("### { name }"),
+             home = case_when(!is.na(homepage) ~ glue("[{ home_symbol } Home]({ homepage })"),
                               TRUE ~ ""),
-             docs = case_when(!is.na(documentation) ~ glue("[{{ book_symbol }} Docs]({{ documentation }})"),
+             docs = case_when(!is.na(documentation) ~ glue("[{ book_symbol } Docs]({ documentation })"),
                               TRUE ~ ""),
-             code = case_when(!is.na(tool_dev_url) ~ glue("[{{ code_symbol }} Code]({{ tool_dev_url }})"),
+             code = case_when(!is.na(tool_dev_url) ~ glue("[{ code_symbol } Code]({ tool_dev_url })"),
                               TRUE ~ ""),
-             links = paste(home, docs, code, glue("`{{ licence }}`"),
+             links = paste(home, docs, code, glue("`{ licence }`"),
                            sep = " &ensp; "),
-             markdown = glue("{{ name }}", "{{ links }}", "{{ description }}",
+             markdown = glue("{ name }", "{ links }", "{ description }",
                              .sep = '\n\n')
       ) %>%
       pull(markdown)
-    cat('## {{{{< fa screwdriver-wrench >}}}} Tools \n\n')
+    cat('## {{< fa screwdriver-wrench >}} Tools \n\n')
     cat(paste(markdown, collapse = "\n\n"))
-}}
+}
 ```