Refactor: Consolidate duplicated model documentation

[clnsmth]

Our current documentation strategy for models is creating maintenance challenges due to duplication. Information is stored in both the models/ directory and again in the vignettes/ directory. This means updates must be made in two places. 😵

Proposed Solution

All model-specific documentation could reside in the models/ directory. The R Markdown files in the vignettes/ directory should reference this content directly rather than storing a copy. ♻️

This can be accomplished by updating the vignettes to use relative paths to access the necessary files from the models/ directory.

[mobb]

I agree - I think it would be a good idea to not tie the model documentation to a particular programming language, but instead use relative links. That way, if someone someday creates (e.g.) a python package, they would follow that pattern, rather than duplicate documentation again.

[mobb]

Can R can work with plain markdown? maybe by storing the header elsewhere. Using plain markdown makes the documentation more generic

[clnsmth]

Hi @mobb,

Anything rendered into the R package vignettes and documentation needs to be in R-markdown format (.Rmd).

Here are a couple of options:

1. Use R-markdown format for the model documentation. It would then be rendered into an HTML webpage for the package's documentation, which could be referenced from anywhere (e.g., a Python package) just like any website.
2. Separate the model documentation from the R package entirely so that it can exist and evolve independently.

I would favor the first option for now, as it reduces the amount of work needed at this time, while still recognizing the second option is likely more optimal in the long run.

What do you think?

[clnsmth]

And, there's a third option.

We could keep the model documentation in plain Markdown format and reference it as a child file for rendering from within the R Markdown document. This would align well with our current documentation, as vignettes/model_overview.Rmd is almost an exact copy of models/table_description.md.

In vignettes/model_overview.Rmd, we would do this:

```{r child-markdown, child='../model/table_description.md'}