Ideas for Improving the Examples Section of all admiral Functions

[sophie-gem]

I've created this area as a place where anyone can 'brain dump' any potential ideas they have to improve the user experience when looking at the examples on the admiral website. Consider for example (I know it's super small - but hopefully it emphasises the point here),

This is the examples section for the derive_param_computed().

So if anyone has any ideas, has seen other R packages where it looks better, etc. please post here and we can decide on the best one! 🙂

[sophie-gem]

This comes from the discussion in #2338. I will add the ideas already provided from there into this discussion thread tomorrow.

[sophie-gem]

@pharmaverse/admiral , @pharmaverse/admiral_comm - please feel free to add any ideas you have!

[bms63]

I love how the gt package is doing their examples, but looks like a lot of manual upkeep. There has got to be a way to automate such tasks.

https://gt.rstudio.com/reference/tab_spanner.html

[sophie-gem]

Excuse if this is just my ignorance - but does there exist a way of 'caching' these r code chunks (a bit like you can with knitr) so it's not re-run each time? As that could potentially speed up the process? Definitely like the way gt does it though - makes it a lot clearer to read. Though perhaps a 'nice to have' (if it's possible), is to have subheadings under Examples (which go into the TOC) which splits it down further?

[bms63]

Doesn't the example code already run every time anyways?

[ddsjoberg]

it runs when we do the R CMD Check, but not every time we document (converting roxygen comments to rd syntax)

[bms63]

oh i see!! yes that could be a little cumbersome!!

Perhaps we should do a canvas of all the functions where this improvement might have the most impact. Some functions are pretty small and maybe don't need this update?? If only a few key functions need this update, then we can stress test and see how cumbersome it might be.

Other idea: Can we link out to an example vignette that is laid out nicer with more detailed examples? Then keep the functions with minimal example and say - checkout the example vignette for a detailed walkthrough of each argument...

[manciniedoardo]

Other idea: Can we link out to an example vignette that is laid out nicer with more detailed examples? Then keep the functions with minimal example and say - checkout the example vignette for a detailed walkthrough of each argument...

I'm not sure about this. I quite like that when you land on the reference page for a function, you have everything you need there on one page - arguments, examples, related functions, etc.

I'd rather do the canvas :)

[bms63]

@sophie-gem do you mind trying an experimenting to see how long the load time for a function with the examples re-rendered from a code chunk and examples without them rendered in the code chunk?

[sophie-gem]

Yes sure - will let you guys know the result!

[manciniedoardo]

Decision: this would be great to purse for maybe 1.3? We could establish a working group (leader tbc) and identify key functions to target for this "improved" reference page. Some could be derive_vars_joined(), derive_param_computed(), imputation functions.

[manciniedoardo]

How does this align with the roclets work done last year by @zdz2101 ?