---
title: "Fisheries Integrated Modeling System (FIMS) Documentation"
vignette: >
  %\VignetteIndexEntry{Fisheries Integrated Modeling System (FIMS) Documentation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, collapse = TRUE, comment = "#>")
```

```{r fims-version, warning=FALSE, message=FALSE, include=FALSE}
FIMS_version <- packageDescription("FIMS")$Version
```

This page provides information related to the FIMS documentation for version `r FIMS_version`.

```{r doc-list, echo=FALSE, warning=FALSE, message=FALSE}
## Document data template
template <- list(
  description = "**Description:** \n",
  audience = "**Audience**: project manager, developer, and user\n",
  link = "**Link**:\n
  \t\t - \n\n",
  update = "**Update frequency**: \n",
  horizontal_line = "---"
)

## Overview
overview <- list(
  description = "**Description:** a summary of critical information (e.g., history of FIMS, organization overview, and technologies and tools used to build FIMS) and operating processes (< 2 pages). Links to additional resources (e.g., Term of reference, technical memos, and manuscripts) can be included in this summary. This document can serve as an initial resource for new team members, addressing fundamental questions they are likely to have.\n",
  audience = "**Audience**: project manager, developer, and user\n",
  link = "**Link**:\n
  \t\t - under development\n",
  update = "**Update frequency**: update the document as requested, particularly if new members encounter difficulties resolving major issues or uncover misinformation while using this document.\n",
  horizontal_line = "---"
)

## Strategic plan
strategic_plan <- list(
  description = "**Description:** define the mission, vision, and strategic plan for FIMS.\n",
  audience = "**Audience**: project manager and developer\n",
  link = "**Link**:\n
  \t\t - [FIMS mission, vision, and strategic plan (NOAA internal only)](https://docs.google.com/document/d/1x-dfG9eu9pEBk2KFUQAO7OdE9XkfZ8wkDNdnOwYGtcY/edit?usp=sharing)\n",
  update = "**Update frequency**: annually update the document at the end of NOAA's fiscal year.\n",
  horizontal_line = "---"
)

## Requirements
requirements <- list(
  description = "**Description:** document the set of requirements requested by regional teams for inclusion in FIMS.\n",
  audience = "**Audience**: developer\n",
  link = "**Link**:\n
  \t\t - [FIMS requirements Google Sheets (NOAA internal only)](https://docs.google.com/spreadsheets/d/1impCdPPob8IPdoiFDpJpe7-Nbdjbz_Uq05_4BWooY4g/edit?usp=sharing)\n
  \t\t - [requirements repository](https://github.com/NOAA-FIMS/requirements)\n",
  update = "**Update frequency**: annually update the document at the end of NOAA's fiscal year.\n",
  horizontal_line = "---"
)

## Developer guide
developer_guide <- list(
  description = "**Description:** this guide helps developers install, configure, and manage FIMS.\n",
  audience = "**Audience**: developer\n",
  link = "**Link**:\n
  \t\t - [FIMS collaborative workflow repository](https://noaa-fims.github.io/collaborative_workflow/)\n
  \t\t - [FIMS Developer Handbook](https://noaa-fims.github.io/collaborative_workflow/)\n",
  update = "**Update frequency**: update the book as per request and bug report.\n",
  horizontal_line = "---"
)

## Design documents
design_documents <- list(
  description = "**Description:** a summary of key decisions regarding the design and architecture of FIMS.\n",
  audience = "**Audience**: developer\n",
  link = "**Link**:\n
  \t\t - [design documents Google Drive folder (NOAA internal only)](https://drive.google.com/drive/folders/1e-7MNRa61uGQaWsixKsyw5rGnRlcrYFf?usp=drive_link)\n",
  update = "**Update frequency**: create the documentation as a design document at the beginning of a milestone, update design decisions throughout development within the milestone, archive it at the end of the milestone. Document design decisions that are not obvious, thereby avoiding needless refactoring in the future or rehashing previously made decisions. At the end of the milestone, we can summarize key pieces of the document and put them into the overview document.\n",
  horizontal_line = "---"
)

## C++ source code documentation
c_code_documentation <- list(
  description = "**Description:** use comments in the code to document C++ files, namespaces, classes, structs, templates, variables, functions, and typedefs.\n",
  audience = "**Audience**: developer and user\n",
  link = "**Link**:\n
  \t\t - [C++ Doxygen website](https://noaa-fims.github.io/FIMS-docs/)\n",
  update = "**Update frequency**: always up to date.\n",
  horizontal_line = "---"
)

## R source code documentation
r_code_documentation <- list(
  description = "**Description:** describe R functions in comments next to their definitions.\n",
  audience = "**Audience**: developer and user\n",
  link = "**Link**:\n
  \t\t - [Function reference](https://noaa-fims.github.io/FIMS/reference/index.html)\n",
  update = "**Update frequency**: always up to date.\n",
  horizontal_line = "---"
)

## Release notes
release_notes <- list(
  description = "**Description:** provide notes associated with each release of FIMS.\n",
  audience = "**Audience**: user\n",
  link = "**Link**:\n
  \t\t - [Changelog](https://noaa-fims.github.io/FIMS/news/index.html)\n",
  update = "**Update frequency**: update before a release.\n",
  horizontal_line = "---"
)

## License
license <- list(
  description = "**Description:** provide full copies of the license statements.\n",
  audience = "**Audience**: user\n",
  link = "**Link**:\n
  \t\t - [License file](https://noaa-fims.github.io/FIMS/LICENSE-text.html)\n",
  update = "**Update frequency**: review the license before a major version release and determine if any updates are necessary.\n",
  horizontal_line = "---"
)

## Case studies
case_studies <- list(
  description = "**Description:** provide test cases of FIMS.\n",
  audience = "**Audience**: developer and user\n",
  link = "**Link**:\n
  \t\t - [case studies website](https://noaa-fims.github.io/case-studies/)\n",
  update = "**Update frequency**: publish test cases within milestone 2 and then update the website as requested.\n",
  horizontal_line = "---"
)

## User guide
user_guide <- list(
  description = "**Description:** describe the available installation options for FIMS. Provide step-by-step procedures for common beginner and advanced FIMS workflows.\n",
  audience = "**Audience**: user\n",
  link = "**Link**:\n
  \t\t - [installation guide in the README file](https://noaa-fims.github.io/FIMS/)\n
  \t\t - [vignettes on the FIMS {pkgdown} website](https://noaa-fims.github.io/FIMS/articles/index.html
)\n",
  update = "**Update frequency**: always up to date (The person making the change is responsible for the update and a dedicated user guide maintainer should check in on it at the end of each milestone).\n",
  horizontal_line = "---"
)

## Combine list of documentation
doc_list <- list(
  " #### **Overview**\n" = overview,
  " #### **Strategic plan**\n" = strategic_plan,
  " #### **Requirements**\n" = requirements,
  " #### **Developer guide**\n" = developer_guide,
  " #### **Design documents**\n" = design_documents,
  " #### **C++ source code documentation**\n" = c_code_documentation,
  " #### **R source code documentation**\n" = r_code_documentation,
  " #### **Release notes**\n" = release_notes,
  " #### **License**\n" = license,
  " #### **Case studies**\n" = case_studies,
  " #### **User guide**\n" = user_guide
)
```

```{r list-to-markdown, echo=FALSE, warning=FALSE, message=FALSE}
library(tidyverse)

list2markdown <- function(list) {
  enframe(list) |>
    group_by(name) |>
    mutate(items = paste0(
      "- ",
      name,
      paste0(
        "\n\t- ",
        unlist(value),
        collapse = ""
      )
    )) |>
    pull(items) |>
    paste0(collapse = "\n") |>
    cat()
}
```
## Documentation list {.tabset}

### Documentation for user 
```{r user-doc, echo=FALSE, warning=FALSE, results='asis'}
list_index <- lapply(doc_list, function(x) {
  grepl("user", x$audience)
})

user_doc <- doc_list[names(list_index)[which(unlist(list_index))]]

user_doc <- lapply(user_doc, "[", c("description", "link", "horizontal_line"))

list2markdown(user_doc)
```

### Documentation for developer 
```{r developer-doc, echo=FALSE, warning=FALSE, results='asis'}
list_index <- lapply(doc_list, function(x) {
  grepl("developer", x$audience)
})

developer_doc <- doc_list[names(list_index)[which(unlist(list_index))]]

developer_doc <- lapply(developer_doc, "[", c("description", "link", "update", "horizontal_line"))

list2markdown(developer_doc)
```

### Documentation for project manager
```{r project-manager-doc, echo=FALSE, warning=FALSE, results='asis'}
list_index <- lapply(doc_list, function(x) {
  grepl("project manager", x$audience)
})

project_manager_doc <- doc_list[names(list_index)[which(unlist(list_index))]]

project_manager_doc <- lapply(project_manager_doc, "[", c("description", "link", "update", "horizontal_line"))

list2markdown(project_manager_doc)
```

### All documentation
```{r all-doc, echo=FALSE, warning=FALSE, results='asis'}
list2markdown(doc_list)
```

## {-}