compatibility with bookdown

[mariev]

Adding bare roxygen blocks in Rmd files that are child bookdown docs throws errors. One alternative is to surround the block with yaml separators, so a requirement can look like:

---
#' @title Function Requirement 001
#' @editor Marie Vendettuoli
#' @editDate 2020-10-12
---

+ Requirement starts here

🤔 Is it too cumbersome to have --- surrounding? Do we need to include support for bookdown? thoughts?

[thebioengineer]

Could you remind me why we were looking at using {bookdown}? Tt was for being able to have dynamic references, correct?

Overall, the --- isn't too distracting for me. One worry though could be folks starting to think about yaml headers and be confused why we are using roxygen tags?

[mariev]

Bookdown allows usage of configuring the report via _bookdown.yml & _output.yml.

It provides a much more accessible interface for compendiums of many child .Rmds, the tradeoff being that test code needs to be captured via .RMD not .R files.

Edit: I will say that it is helpful that we are explicit if we choose not to support bookdown, because there is a general user expectation that most of what works for rmarkdown natively extends to bookdown. It would be frustrating for users to discover this via trial and error.

[mariev]

@elimillera I saw your mention of using .validation yaml in a pkgdown-like manner e.g. by being able to list ordering of reqs/test cases/ test code files. 🤔 about our past discussions re: bookdown support, and wondering if we can frame .validation as "bookdown-like"?

[thebioengineer]

are we saying we would add to .validation the configuration of the validation report?

[elimillera]

@mariev Can you clarify what you mean by bookdown-like? I was just thinking YAML would be a nice way to specify style, ordering, etc. I haven't thought about using bookdown for this context but I think that's a really good idea if we can maintain compatibility with all the tools we can.

@thebioengineer I think that would be nice functionality if people are able to specify how the report is rendered and preserver that.

[mariev]

Comparing .validation to the contents of _bookdown.yml:

Superficially, our .validation file includes details that are captured in bookdown fields book_filename and output_dir.

If we include a listing of req/test case/test code child files, that would add similar functionality to the rmd_files field.

edit: pointing out that we would be implementing "bookdown-like" because bookdown natively does not play nicely with the structure we have chosen for req/test case files. The roxy blocks cause an error unless surrounded by "---".

• https://bookdown.org/yihui/bookdown/usage.html#usage
• https://bookdown.org/yihui/bookdown/configuration.html

[mariev]

summarizing today's decision via Teams mtg:

• add field for listing reqs/test case/test code files in .validation to scrape via vt_use_report (#45)
• change .validation to .validation.yml (#50 )
• no expectation of bookdown support.