Use shinylive to show the app on the README

[llrs-roche]

Pull Request

Fixes #1404

Converted the README.md to README.Rmd to be able to genereate a shinylive of the example app.
The space modifications are automatically but I just made very few modifications to the file: add some code chunk options and two chunks at the end.
It adds some steps on the docs.yaml to render the README (iff modified).

Note: I haven't removed the preview yet (I want to see how it works and then I'll remove it).

There is a comment about having a git hook locally. usethis::use_readme_rmd() generates a hook to be added to .git/hooks/pre-commit (not sure if this could be shared via .pre-commit-config.yaml).

Hook

#!/bin/bash
README=($(git diff --cached --name-only | grep -Ei '^README\.[R]?md$'))
MSG="use 'git commit --no-verify' to override this check"

if [[ ${#README[@]} == 0 ]]; then
  exit 0
fi

if [[ README.Rmd -nt README.md ]]; then
  echo -e "README.md is out of date; please re-knit README.Rmd\n$MSG"
  exit 1
elif [[ ${#README[@]} -lt 2 ]]; then
  echo -e "README.Rmd and README.md should be both staged\n$MSG"
  exit 1
fi

[github-actions]

Unit Tests Summary

  1 files   27 suites   10m 22s ⏱️
274 tests 270 ✅ 4 💤 0 ❌
534 runs  530 ✅ 4 💤 0 ❌

Results for commit 7950690.

♻️ This comment has been updated with latest results.

[github-actions]

Unit Test Performance Difference

Test Suite	$Status$	Time on main	$±Time$	$±Tests$	$±Skipped$	$±Failures$	$±Errors$
module_session_info	💚	$20.37$	$-3.74$	$0$	$0$	$0$	$0$
shinytest2-data_summary	💚	$50.96$	$-2.26$	$0$	$0$	$0$	$0$
shinytest2-filter_panel	💚	$42.12$	$-1.14$	$0$	$0$	$0$	$0$
shinytest2-init	💚	$28.27$	$-2.51$	$0$	$0$	$0$	$0$
shinytest2-landing_popup	💚	$44.86$	$-1.58$	$0$	$0$	$0$	$0$
shinytest2-module_bookmark_manager	💚	$36.81$	$-2.19$	$0$	$0$	$0$	$0$
shinytest2-modules	💚	$39.64$	$-1.98$	$0$	$0$	$0$	$0$
shinytest2-reporter	💚	$67.99$	$-2.32$	$0$	$0$	$0$	$0$

Additional test case details

Test Suite	$Status$	Time on main	$±Time$	Test Case
module_session_info	💚	$20.35$	$-3.74$	creation_process_is_invoked_for_teal.lockfile.mode_enabled_and_snapshot_is_copied_to_teal_app.lock_and_removed_after_session_ended

Results for commit 11387bd

♻️ This comment has been updated with latest results.

[github-actions]

Code Coverage Summary

Filename                          Stmts    Miss  Cover    Missing
------------------------------  -------  ------  -------  ----------------------------------------------------------------------------------------------------------------------------------------
R/checkmate.R                        24       0  100.00%
R/dummy_functions.R                  67      11  83.58%   46, 48, 90-98
R/include_css_js.R                   22      17  22.73%   12-38, 76-82
R/init.R                            142      96  32.39%   141-162, 192-200, 210-235, 238-239, 246-255, 258-267, 270-279, 283-293, 295
R/landing_popup_module.R             34      34  0.00%    22-57
R/module_bookmark_manager.R         158     127  19.62%   47-68, 88-138, 143-144, 156, 203, 238-315
R/module_data_summary.R             203      37  81.77%   25-53, 67, 77, 231, 262-266
R/module_filter_data.R               64       2  96.88%   22-23
R/module_filter_manager.R           230      57  75.22%   56-62, 73-82, 90-95, 108-112, 117-118, 291-314, 340, 367, 379, 386-387
R/module_init_data.R                 74       0  100.00%
R/module_nested_tabs.R              227      84  63.00%   40-136, 168, 193-195, 346
R/module_session_info.R              18       7  61.11%   35-41
R/module_snapshot_manager.R         216     146  32.41%   89-95, 104-113, 121-133, 152-153, 170-180, 184-199, 201-208, 215-230, 234-238, 240-246, 249-262, 265-273, 303-317, 320-331, 334-340, 354
R/module_teal_data.R                149      76  48.99%   43-149
R/module_teal_lockfile.R            131      55  58.02%   33-37, 45-57, 60-62, 76, 86-88, 92-96, 100-102, 110-119, 122, 124, 126-127, 161-162, 196-201
R/module_teal_with_splash.R          33      33  0.00%    24-61
R/module_teal.R                     158      56  64.56%   50-107, 124, 138-139, 178
R/module_transform_data.R           126       7  94.44%   20, 59, 142-146
R/modules.R                         285      53  81.40%   174-178, 233-236, 360-380, 388, 394, 571-577, 590-598, 613-628, 674, 687
R/reporter_previewer_module.R        19       1  94.74%   34
R/show_rcode_modal.R                 24      24  0.00%    17-42
R/tdata.R                            14      14  0.00%    19-61
R/teal_data_module-eval_code.R       24       0  100.00%
R/teal_data_module-within.R           7       0  100.00%
R/teal_data_module.R                 20       0  100.00%
R/teal_data_utils.R                  10       0  100.00%
R/teal_modifiers.R                   71      71  0.00%    26-214
R/teal_reporter.R                    70       8  88.57%   69, 77-82, 131-132, 135, 152
R/teal_slices-store.R                29       0  100.00%
R/teal_slices.R                      63       0  100.00%
R/teal_transform_module.R            45       0  100.00%
R/TealAppDriver.R                   376     376  0.00%    56-765
R/utils.R                           250      38  84.80%   400-449
R/validate_inputs.R                  32       0  100.00%
R/validations.R                      58      37  36.21%   118-406
R/zzz.R                              15      11  26.67%   4-18
TOTAL                              3488    1478  57.63%

Diff against main

Filename      Stmts    Miss  Cover
----------  -------  ------  --------
TOTAL             0       0  +100.00%

Results for commit: 7950690

Minimum allowed coverage is 80%

♻️ This comment has been updated with latest results

[llrs-roche]

From pkgdown::build_home():

If you use index.Rmd or README.Rmd it's your responsibility to knit the document to create the corresponding .md. pkgdown does not do this for you because it only touches files in the ⁠doc/⁠ directory.

If we want to include the app we'll need a different README for the repo/github view and another for github pages. This would require tweaking the action on insightsengineering/r.pkg.template/.github/workflows/pkgdown.yaml@main to pick the right README.md as it currently pulls the repository from a branch (or that a commit is made directly to that branch). This becomes quite complicated and wouldn't be ready for the release tomorrow.

Adding a link it is fairly simple and portable: I'll keep the video recorded and just the link to where users can visualize the output.

[m7pr]

There is #1404 (comment) about having a git hook locally. usethis::use_readme_rmd() generates a hook to be added to .git/hooks/pre-commit (not sure if this could be shared via .pre-commit-config.yaml).

Our .pre-commit-confit.yaml is based on https://github.com/lorenzwalthert/precommit which has this hook already included:
https://github.com/lorenzwalthert/precommit/blob/main/.pre-commit-hooks.yaml#L59

You just need to extend .pre-commit-confit.yaml with

      - id: readme-rmd-rendered
        name: Render README.md

[m7pr]

@llrs-roche

From pkgdown::build_home():

If you use index.Rmd or README.Rmd it's your responsibility to knit the document to create the corresponding .md. pkgdown does not do this for you because it only touches files in the ⁠doc/⁠ directory.

If we want to include the app we'll need a different README for the repo/github view and another for github pages.

I don't understand this. The docs action has a step that renders README.Rmd to Readme.md right? This Readme.md is committed to the rspository. And then pkgdown, in the next step, takes the freshly knitted Readme.md. So why we want two README?

[llrs-roche]

Yes, the README.Rmd is rended to README.md and committed to the repository. I've added the job on the docs.yaml to render the README file, but this is only to ensure the file is up to date.

The README.Rmd must be rendered to a README.md so that pkgdown can use it.
But README.md won't have the shinylive_iframe if rendered with requireNamespace("roxy.shinylive", quietly = TRUE) && knitr::is_html_output() && identical(Sys.getenv("IN_PKGDOWN"), "true"):

• It is not an html_output: it is github_document/md

• It doesn't have the IN_PKGDOWN: Easy to add to the Github Action

• Even if we removed that and used just eval = requireNamespace("roxy.shinylive", quietly = TRUE) the output format doesn't allow to include the iframes:

  Quitting from lines 143-144 [shinylive_iframe] (README.Rmd)
  Error in s$close() : attempt to apply non-function
  Error: 
  ! in callr subprocess.
  Caused by error in `s$close()`:
  ! attempt to apply non-function
  ℹ See `$stdout` for standard output.
  Type .Last.error to see the more details.
  

If we want to include we would need to render it into different format but not sure how it would play with the CI and the pkgdown internal machinery.

[m7pr]

If we want to include we would need to render it into different format but not sure how it would play with the CI and the pkgdown internal machinery.

Yeah, so the action can render into index.html and into README.md and I think it should be fine. Action can also remove any unnecessary chunk options that will be problematic or unused in README.md by GitHub when showing the welcome page on the repository.

I would suggest rendering README.Rmd into 2 files: index.html and README.md

[vedhav]

Let me raise a small PR to just add the shinylive in the Getting started vignette. Readme can wait, but I think the getting started vignette can go in before the release.

[vedhav]

Can any one of you just review this PR #1491?

[pawelru]

this condition probably needs some rework
this is very specific to the vigniette that we want to have only in pkgdown website but not in the help panel. I don't think this holds true here.
For instance, I think it's reasonable to expect this to be rendered in the GitHub preview here: https://github.com/insightsengineering/teal/tree/1404_shinylive_readme%40main?tab=readme-ov-file

[llrs-roche]

Thanks for the feedback! I'm not sure we can insert iframes on markdown format with knitr. See the error message when I simplified the condition: #1490 (comment). Some sites say iframes are supported while other says it is disabled due to security concerns. But this might be a knitr limitation as I saw some comments about using some flags on pandoc to insert iframes.

In addition, if we want the iframe to show on the pkgdown index.html we need to render it to markdown ourselves as pkgdown won't do it (see this previous comment). But it might take time to do this on the GHA and won't be ready for today's release.

[pawelru]

ok thanks for the reply. I agree - let's not block the release because of that and let's investigate this afterwards

[llrs-roche]

The shinylive is not included on the pkgdown file. Test code:

# Build the README.md for repository
devtools::build_readme()

# Build the index.md for pkgdown
Sys.setenv(IN_PKGDOWN = "true")
devtools::build_readme(output_format = "html_document", output_file = "index.html")
knitr::knit("index.html", output = "index.md")

# Check website
unlink("index.html") # Delete just in case it is not overwritten
pkgdown::build_home() # Build index.html file from the index.md file

If we follow this instructions we will see that index.md has the iframe code <iframe src="https://shinylive.io/r/app/ on line 539 (grep -n "<iframe src=" index.md). But it won't show up on the index.html generated by pkgdown:

I think adding a link to the README and pkgdown home page is the best we can do for now. In addition, the index.md is a 2.7Mb file that is very slow to open (it crashed my computer), not sure if GitHub pages will render that directly (see also previous comments suggesting it is not possible to render iframes).

[pawelru]

Yeah indeed - looks like iframe is not supported as per official docs.

I have one more idea but a little bit more difficult: a separate index.Rmd file that renders into README.md (without iframe) and index.md (with iframe). Then in pkgdown we say that index.md should be used (instead of README.md). This way we can achieve iframe in pkgdown at least. WDYT?

[llrs-roche]

@pawelru The script above generates an index.md with an iframe. But pkgdown doesn't include the iframe when built locally (see the screenshot). I don't think building the website differently would fix that, I don't see any parameter that could help.

There are some issues regarding iframes on pkgdown issue tracker, but nothing about shinylive (yet?). In general it is mentioned as a workaround around an issue.