From 801542b14edf4433059c05ddc307e082d3419175 Mon Sep 17 00:00:00 2001 From: Bai-Li-NOAA Date: Thu, 16 May 2024 18:04:49 -0400 Subject: [PATCH] doc: add documentation tabset and organize vignettes - post documentation for users, developers, and project managers - reorganize vignettes under appropriate sectionss - remove the navbar for articles to ensure no articles are hidden --- DESCRIPTION | 1 + pkgdown/_pkgdown.yml | 7 +- pkgdown/extra.css | 2 +- vignettes/fims-documentation.Rmd | 226 +++++++++++++++++++++++++++++++ 4 files changed, 232 insertions(+), 4 deletions(-) create mode 100644 vignettes/fims-documentation.Rmd diff --git a/DESCRIPTION b/DESCRIPTION index 9db01632f..de1550036 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -69,6 +69,7 @@ Suggests: remotes, rmarkdown, testthat (>= 3.0.0), + tidyverse, usethis LinkingTo: Rcpp, diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index cd17f34e5..c8a1c77c1 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -18,12 +18,13 @@ template: articles: - title: Fisheries Integrated Modeling System (FIMS) - navbar: ~ contents: - - fims-path-maturity + - fims-documentation + - fims-demo + - title: Developer contents: - - fims-demo + - fims-path-maturity reference: - title: Data diff --git a/pkgdown/extra.css b/pkgdown/extra.css index e8865935c..5f999424e 100644 --- a/pkgdown/extra.css +++ b/pkgdown/extra.css @@ -1 +1 @@ -@import url("https://nmfs-fish-tools.github.io/nmfspalette/extra.css"); \ No newline at end of file +@import url("https://nmfs-fish-tools.github.io/nmfspalette/extra.css"); diff --git a/vignettes/fims-documentation.Rmd b/vignettes/fims-documentation.Rmd new file mode 100644 index 000000000..d1efaa565 --- /dev/null +++ b/vignettes/fims-documentation.Rmd @@ -0,0 +1,226 @@ +--- +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) +``` + +## {-}