R & C++ documentation helper function

CMakeLists.txt

@@ -78,6 +78,7 @@ IF(BUILD_DOC)
   set(DOXYGEN_AUTOLINK_SUPPORT YES)
   set(DOXYGEN_OUTPUT_DIRECTORY "${PROJECT_SOURCE_DIR}/doxygen")
   set(DOXYGEN_HTML_OUTPUT "html")
+  set(DOXYGEN_GENERATE_TAGFILE "doxygen/html/FIMS.tag")
 
   doxygen_add_docs(fims_doxygen
     inst/include

NAMESPACE

@@ -33,6 +33,7 @@ export(augment)
 export(clear)
 export(create_default_configurations)
 export(create_default_parameters)
+export(fims_help)
 export(fit_fims)
 export(get_ages)
 export(get_data)
@@ -99,7 +100,15 @@ importFrom(generics,augment)
 importFrom(generics,glance)
 importFrom(generics,tidy)
 importFrom(graphics,plot)
+importFrom(htmltools,browsable)
+importFrom(htmltools,tags)
 importFrom(rlang,":=")
 importFrom(rlang,.data)
 importFrom(rlang,.env)
+importFrom(utils,adist)
+importFrom(utils,download.file)
+importFrom(xml2,read_xml)
+importFrom(xml2,xml_find_all)
+importFrom(xml2,xml_find_first)
+importFrom(xml2,xml_text)
 useDynLib(FIMS, .registration = TRUE)

R/fims_help.R

@@ -0,0 +1,105 @@
+#' Smart FIMS Documentation Finder
+#'
+#' @param query A string representing the function or class to search for.
+#'
+#' @importFrom utils adist download.file
+#' @importFrom xml2 read_xml xml_find_all xml_find_first xml_text
+#' @importFrom htmltools browsable tags
+#'
+#' @export
+#' @examples
+#' \dontrun{
+#' # Search for an R function's documentation in the pkgdown site
+#' fims_help("FIMSFrame")
+#'
+#' # Search for a C++ class's documentation in the Doxygen site
+#' fims_help("FIMSLog")
+#'
+#' # The function also handles partial, case-insensitive matches for C++ entities
+#' fims_help("bevertonholt")
+#' }
+fims_help <- function(query) {
+  # Do not run in non-interactive sessions (e.g., R CMD check)
+  if (!interactive()) {
+    message("fims_help() is designed for interactive use only.")
+    return(invisible(NULL))
+  }
+  target_url <- NULL
+
+  doxygen_base_url <- "https://e-perl-noaa.github.io/FIMS/doxygen/"
+  r_base_url <- "https://noaa-fims.github.io/FIMS/" # Adjust to your pkgdown path
+
+  # Check native R exports first
+  if (query %in% getNamespaceExports("FIMS")) {
+    target_url <- paste0(r_base_url, "reference/", query, ".html")
+  } else {
+    # Setup caching for the Doxygen Tagfile
+    tagfile_url <- paste0(doxygen_base_url, "FIMS.tag")
+    cache_dir <- tempdir()
+    local_tagfile <- file.path(cache_dir, "FIMS.tag")
+
+    # Download the tagfile only if we haven't already in this R session
+    if (!file.exists(local_tagfile)) {
+      message("Fetching FIMS C++ documentation index...")
+      tryCatch(
+        utils::download.file(tagfile_url, destfile = local_tagfile, quiet = TRUE),
+        error = function(e) stop("Could not download FIMS.tag. Check internet connection.")
+      )
+    }
+
+    tag_data <- xml2::read_xml(local_tagfile)
+
+    # Extract ALL names from the XML
+    compound_names_nodes <- xml2::xml_find_all(tag_data, "//compound/name")
+    compound_names <- xml2::xml_text(compound_names_nodes)
+
+    # Extract unique names and find partial, case-insensitive matches
+    unique_names <- unique(compound_names)
+    matched_names <- unique_names[grep(query, unique_names, ignore.case = TRUE)]
+
+    if (length(matched_names) == 0) {
+      # If no direct matches, try to find close matches for a "Did you mean?" feature
+      distances <- utils::adist(query, unique_names, ignore.case = TRUE)
+      # Find suggestions within a reasonable distance (e.g., distance of 2)
+      suggestions <- unique_names[which(distances <= 2)]
+
+      message(sprintf("No C++ match found for '%s'.", query))
+      if (length(suggestions) > 0) {
+        message("Did you mean one of these?")
+        for (suggestion in suggestions) {
+          message(paste("  -", suggestion))
+        }
+      }
+    } else {
+      # If multiple unique matches exist, let the user know!
+      if (length(matched_names) > 1) {
+        message("Multiple unique C++ matches found:")
+        for (name in matched_names) {
+          message(paste("  -", name))
+        }
+        message(sprintf("\nLoading the first match ('%s'). Refine your query to view others.", matched_names[1]))
+      } else {
+        message(sprintf("Found C++ match: '%s'. Loading...", matched_names[1]))
+      }
+
+      best_match_name <- matched_names[1]
+
+      # Now use the exact unique name to find the parent node and extract the filename
+      xpath_query <- sprintf("//compound[name[text()='%s']]", best_match_name)
+      match_node <- xml2::xml_find_first(tag_data, xpath_query)
+
+      filename <- xml2::xml_text(xml2::xml_find_first(match_node, ".//filename"))
+      target_url <- paste0(doxygen_base_url, filename)
+    }
+  }
+
+  if (!is.null(target_url)) {
+    # Render in the Viewer Pane
+    viewer_html <- htmltools::browsable(
+      htmltools::tags$iframe(src = target_url, width = "100%", height = "600px", style = "border:none;")
+    )
+
+    print(viewer_html)
+    invisible(target_url)
+  }
+}

doxygen/header.html

@@ -48,8 +48,8 @@
     <nav class="navbar navbar-expand-lg " data-bs-theme="auto">
       <div class="navbar-container container-fluid">
         <div class="navbar-brand-container mx-auto">
-          <a href="https://noaa-fims.github.io/" class="navbar-brand navbar-brand-logo"></a>
-          <a class="navbar-brand" href="https://noaa-fims.github.io/">
+          <a href="https://e-perl-noaa.github.io/" class="navbar-brand navbar-brand-logo"></a>
+          <a class="navbar-brand" href="https://e-perl-noaa.github.io/">
           </a>
         </div>
         <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarCollapse" aria-controls="navbarCollapse" role="menu" aria-expanded="false" aria-label="Toggle navigation">
@@ -63,8 +63,8 @@
             <button class="nav-link dropdown-toggle" type="button" id="dropdown-reference" data-bs-toggle="dropdown"
                     aria-expanded="false" aria-haspopup="true">reference</button>
             <ul class="dropdown-menu" aria-labelledby="dropdown-reference">
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/reference/index.html">r/roxygen</a></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/doxygen/index.html">c++/doxygen</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/reference/index.html">r/roxygen</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/doxygen/index.html">c++/doxygen</a></li>
             </ul>
            </li>
 
@@ -73,22 +73,22 @@
                     aria-expanded="false" aria-haspopup="true">articles</button>
             <ul class="dropdown-menu" aria-labelledby="dropdown-articles">
               <li><h6 class="dropdown-header" data-toc-skip>intro to fims</h6></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/articles/fims-demo.html">introducing the fisheries integrated modeling system (fims)</a></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/articles/fims-input-data.html">introducing FIMS input data</a></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/articles/fims-logging.html">introducing the fims logging system</a></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/articles/fims-user-setup-guide.html">fims user setup guide</a></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/articles/fims-demo-projections.html">simple projections using fims</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/articles/fims-demo.html">introducing the fisheries integrated modeling system (fims)</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/articles/fims-input-data.html">introducing FIMS input data</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/articles/fims-logging.html">introducing the fims logging system</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/articles/fims-user-setup-guide.html">fims user setup guide</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/articles/fims-demo-projections.html">simple projections using fims</a></li>
               <li><hr class="dropdown-divider"></li>
               <li><h6 class="dropdown-header" data-toc-skip>developer</h6></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/articles/adding-new-module.html">adding a new c++ module</a></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/articles/fims-path-maturity.html">fims path - maturity</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/articles/adding-new-module.html">adding a new c++ module</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/articles/fims-path-maturity.html">fims path - maturity</a></li>
               <li><hr class="dropdown-divider"></li>
               <li><h6 class="dropdown-header" data-toc-skip>c++ training</h6></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/articles/training-intro-cpp.html">intro to c++</a></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/articles/training-intro-rcpp.html">intro to rcpp</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/articles/training-intro-cpp.html">intro to c++</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/articles/training-intro-rcpp.html">intro to rcpp</a></li>
               <li><hr class="dropdown-divider"></li>
               <li><h6 class="dropdown-header" data-toc-skip>research and development</h6></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/articles/RD-re-sparsity.html">re sparsity</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/articles/RD-re-sparsity.html">re sparsity</a></li>
             </ul>
           </li>
 
@@ -98,7 +98,7 @@
                 <li><h6 class="dropdown-header" data-toc-skip="">Releases</h6></li>
                 <li><a class="external-link dropdown-item" href="https://github.com/NOAA-FIMS/FIMS/releases/latest">latest release</a></li>
                 <li><hr class="dropdown-divider"></li>
-                <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/news/index.html">changelog</a></li>
+                <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/news/index.html">changelog</a></li>
               </ul>
             </li>
 
@@ -107,7 +107,7 @@
                     aria-expanded="false" aria-haspopup="true">reports</button>
             <ul class="dropdown-menu" aria-labelledby="dropdown-reports">
               <li><a class="dropdown-item" href="https://app.codecov.io/gh/NOAA-FIMS/FIMS" target="_blank">coverage (codecov)</a></li>
-              <li><a class="dropdown-item" href="https://noaa-fims.github.io/FIMS/testdown/index.html">testdown</a></li>
+              <li><a class="dropdown-item" href="https://e-perl-noaa.github.io/FIMS/testdown/index.html">testdown</a></li>
             </ul>
           </li>
 

inst/WORDLIST

@@ -16,10 +16,12 @@ Baranov
 basicfsa
 Bertalanffy
 Beverton
+bevertonholt
 Bigg
 bindenv
 Bjarne
 bookdown
+browsable
 byrow
 CALLDEFS
 catchability
@@ -42,6 +44,7 @@ dataframe
 dataframes
 DCMAKE
 deqn
+destfile
 dlognorm
 dmultinorm
 Doering
@@ -73,6 +76,7 @@ googletest
 gtest
 gtests
 hkin
+htmltools
 IBMCPP
 ilist
 INAA
@@ -200,6 +204,7 @@ stockplotr
 subfolders
 subvector
 syms
+tagfile
 TESTDOWN
 testthat
 tibble