diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index dfc640e..50da71a 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -31,6 +31,18 @@ The repository includes a `.github/workflows/copilot-setup-steps.yml` workflow t 6. Run `devtools::document()` to generate documentation 7. Run `devtools::check()` to validate your package +## Version Management + +**CRITICAL**: When creating a new branch or PR from main, ALWAYS increment the development version number in the DESCRIPTION file to one version past the current main branch version. + +For example: +- If main branch has version `0.0.0.9005` +- Your new branch MUST have version `0.0.0.9006` + +This ensures that package versions remain unique across branches and prevents version conflicts. + +**Before finishing each coding session**: Fetch the main branch and increment the development version if your branch is not ahead of main, before committing and requesting review again. + ## Development Workflow ### Building and Checking diff --git a/.github/scripts/add-format-links.R b/.github/scripts/add-format-links.R index e473a1b..47136bf 100755 --- a/.github/scripts/add-format-links.R +++ b/.github/scripts/add-format-links.R @@ -1,12 +1,12 @@ #!/usr/bin/env Rscript # Post-process pkgdown HTML files to add "Other Formats" links -# This script adds links to RevealJS presentations in the pkgdown HTML output +# This script adds links to RevealJS presentations and DOCX documents in the pkgdown HTML output cat("Adding format links to pkgdown articles...\n") cat(sprintf("Working directory: %s\n", getwd())) -# Find all HTML files in docs/articles that have corresponding RevealJS versions +# Find all HTML files in docs/articles that have corresponding alternate format versions # Exclude the RevealJS files themselves (those ending with -revealjs.html) html_files <- list.files( path = "docs/articles", @@ -43,10 +43,17 @@ for (html_file in html_files) { # Check if there's a corresponding RevealJS file revealjs_file <- file.path("docs/articles", paste0(base_name, "-revealjs.html")) + # Check if there's a corresponding DOCX file + docx_file <- file.path("docs/articles", paste0(base_name, ".docx")) + cat(sprintf("Checking for RevealJS file: %s\n", revealjs_file)) + cat(sprintf("Checking for DOCX file: %s\n", docx_file)) + + has_revealjs <- file.exists(revealjs_file) + has_docx <- file.exists(docx_file) - if (!file.exists(revealjs_file)) { - cat(sprintf(" RevealJS file not found, skipping %s\n", basename(html_file))) + if (!has_revealjs && !has_docx) { + cat(sprintf(" No alternate format files found, skipping %s\n", basename(html_file))) next } @@ -55,14 +62,22 @@ for (html_file in html_files) { # Read the HTML content html_content <- readLines(html_file, warn = FALSE) - # Create the format link HTML + # Build the format links HTML + format_links <- character() + if (has_revealjs) { + format_links <- c(format_links, sprintf('
  • RevealJS
  • ', base_name)) + } + if (has_docx) { + format_links <- c(format_links, sprintf('
  • Word
  • ', base_name)) + } + format_link_html <- sprintf('

    Other Formats

    -
    ', base_name) +', paste(format_links, collapse = "\n")) # Find the location to insert the link (after the TOC, before main content) # Look for the nav closing tag or the main content div @@ -99,7 +114,12 @@ for (html_file in html_files) { # Write the modified HTML back writeLines(html_content, html_file) - cat(sprintf(" Added RevealJS link to %s\n", basename(html_file))) + + # Report what was added + added_formats <- character() + if (has_revealjs) added_formats <- c(added_formats, "RevealJS") + if (has_docx) added_formats <- c(added_formats, "DOCX") + cat(sprintf(" Added %s link(s) to %s\n", paste(added_formats, collapse = " and "), basename(html_file))) } else { cat(sprintf(" Could not find insertion point in %s\n", basename(html_file))) } diff --git a/.github/scripts/pre-render-quarto.R b/.github/scripts/pre-render-quarto.R index 2e6490a..8e9a646 100755 --- a/.github/scripts/pre-render-quarto.R +++ b/.github/scripts/pre-render-quarto.R @@ -27,15 +27,41 @@ if (length(qmd_files) == 0) { errors <- character() for (qmd_file in qmd_files) { cat(sprintf("Rendering %s...\n", qmd_file)) - tryCatch({ - # Render to all formats specified in the document YAML - quarto::quarto_render(qmd_file, output_format = "all", quiet = FALSE) - cat(sprintf("Successfully rendered %s\n", qmd_file)) - }, error = function(e) { - error_msg <- sprintf("Error rendering %s: %s", qmd_file, e$message) - cat(error_msg, "\n") - errors <<- c(errors, error_msg) - }) + + # Get the formats defined in the file's YAML + # We'll render each format separately to avoid hanging issues + formats_to_render <- c("html", "revealjs", "docx") + + for (format in formats_to_render) { + # Try up to 2 times in case of transient failures + max_attempts <- 2 + attempt <- 1 + success <- FALSE + + while (attempt <= max_attempts && !success) { + tryCatch({ + if (attempt > 1) { + cat(sprintf("Retry attempt %d for %s to %s\n", attempt, qmd_file, format)) + Sys.sleep(2) # Small delay before retry + } + # Render to specific format + quarto::quarto_render(qmd_file, output_format = format, quiet = FALSE) + cat(sprintf("Successfully rendered %s to %s\n", qmd_file, format)) + success <- TRUE + }, error = function(e) { + error_msg <- sprintf("Error rendering %s to %s (attempt %d): %s", qmd_file, format, attempt, e$message) + cat(error_msg, "\n") + if (attempt >= max_attempts) { + errors <<- c(errors, error_msg) + } + attempt <<- attempt + 1 + }) + + if (!success) { + attempt <- attempt + 1 + } + } + } } cat("Pre-rendering complete!\n") diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 5a6b038..9539339 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -118,11 +118,32 @@ jobs: id: build shell: Rscript {0} run: | + # Build the site (Quarto articles are not in _pkgdown.yml to prevent pkgdown from rendering them) pkg <- pkgdown::as_pkgdown(".") - # Build the site locally pkgdown::build_site(pkg, preview = FALSE, install = FALSE) - - - name: Post-process to add RevealJS format links + + # Copy pre-rendered Quarto HTML files and alternate formats to docs/articles + quarto_files <- c( + "vignettes/quarto_vignette.html", + "vignettes/articles/quarto_article.html" + ) + for (src in quarto_files) { + if (file.exists(src)) { + dest <- file.path("docs/articles", basename(src)) + file.copy(src, dest, overwrite = TRUE) + cat("Copied:", src, "to", dest, "\n") + } + } + + # Copy alternate format files (RevealJS and DOCX) + alt_files <- list.files("vignettes", pattern = "(-revealjs\\.html|\\.docx)$", full.names = TRUE, recursive = TRUE) + for (src in alt_files) { + dest <- file.path("docs/articles", basename(src)) + file.copy(src, dest, overwrite = TRUE) + cat("Copied alternate format:", src, "to", dest, "\n") + } + + - name: Post-process to add alternate format links run: | set -e Rscript .github/scripts/add-format-links.R diff --git a/NEWS.md b/NEWS.md index 1ce9631..0d16401 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,8 @@ # rpt (development version) +* Added DOCX (Word document) format for Quarto vignettes and articles in pkgdown documentation, alongside existing RevealJS format. HTML pages now display an "Other Formats" section with links to both slide and Word document versions + * Fixed rendering issue by rendering each format separately instead of using "all" to avoid hanging + * Conditionally excluded Mermaid diagrams from DOCX format using `.content-visible unless-format="docx"` (Mermaid diagrams remain in HTML and RevealJS outputs) * Updated lintr configuration to match serodynamics reference with enhanced linter rules * PR preview comments now use `recreate: true` to ensure they always appear at the bottom of the PR conversation, preventing them from being hidden in collapsed sections (#31) diff --git a/_pkgdown.yml b/_pkgdown.yml index 5f84df2..6571237 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -14,7 +14,4 @@ articles: navbar: ~ contents: - getting-started - - quarto_vignette -- title: Advanced Topics - contents: articles/quarto_article diff --git a/inst/WORDLIST b/inst/WORDLIST index f08dbe0..9872110 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -3,6 +3,7 @@ CMD Callouts CodeFactor Codecov +DOCX Lifecycle RevealJS Tabsets @@ -10,6 +11,7 @@ ackage callout callouts cdot +docx emplate foldable frac diff --git a/vignettes/.gitignore b/vignettes/.gitignore index ad29309..723352b 100644 --- a/vignettes/.gitignore +++ b/vignettes/.gitignore @@ -1,2 +1,4 @@ /.quarto/ **/*.quarto_ipynb +*.docx +*-revealjs.html diff --git a/vignettes/articles/quarto_article.qmd b/vignettes/articles/quarto_article.qmd index 2d1aa7f..fa15a71 100644 --- a/vignettes/articles/quarto_article.qmd +++ b/vignettes/articles/quarto_article.qmd @@ -6,6 +6,8 @@ format: html: default revealjs: output-file: quarto_article-revealjs.html + docx: + output-file: quarto_article.docx pkgdown: as_is: true --- @@ -220,6 +222,7 @@ print(result) # <4> 3. Apply the example function from the package 4. Display the results +::: {.content-visible unless-format="docx"} ## Diagrams with Mermaid ```{mermaid} @@ -230,6 +233,7 @@ flowchart LR C --> D[Output Results] D --> E[Visualize] ``` +::: ## Mathematical Notation diff --git a/vignettes/quarto_vignette.qmd b/vignettes/quarto_vignette.qmd index b59b215..176b983 100644 --- a/vignettes/quarto_vignette.qmd +++ b/vignettes/quarto_vignette.qmd @@ -4,6 +4,8 @@ format: html: default revealjs: output-file: quarto_vignette-revealjs.html + docx: + output-file: quarto_vignette.docx pkgdown: as_is: true vignette: >