Merge pull request #17 from A2-ai/documentation

Documentation

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: slurmtools
 Title: slurm tooling 
-Version: 0.0.0.9000
+Version: 0.0.0.9001
 Authors@R: c(person("Devin", "Pastoor", , "[email protected]", role = c("aut", "cre")),
     person("Jenna", "Elwing", email = "[email protected]", role = "aut"),
     person("Matthew", "Smith", email = "[email protected]", role = "aut"))

R/attach.R

@@ -34,7 +34,7 @@ slurmtools_options_message <- function() {
   }
 
   #format .onAttach message
-  msg <- ""
+  msg <- "\n\n"
   if (length(set_options)) {
     msg <- paste0(
       msg,
@@ -59,6 +59,6 @@ slurmtools_options_message <- function() {
     )
   }
 
-  msg
+  paste0(msg, "\n\n")
 }
 

R/get-jobs.R

@@ -1,6 +1,12 @@
 utils::globalVariables(c("user_name"))
 
-# Function to parse each job into a tibble row
+#' Function to parse each job into a tibble row
+#'
+#' @param job output from parse_jobs_json
+#'
+#' @return tibble of parsed jobs
+#' @keywords internal
+#' @noRd
 parse_job_to_row <- function(job) {
   # check options for squeue version
   # alter parsing based on result
@@ -37,6 +43,13 @@ parse_job_to_row <- function(job) {
   )
 }
 
+#' Function to transform squeue --json output into named list
+#'
+#' @param .json output from squeue --json call
+#'
+#' @return list of parsed output
+#' @keywords internal
+#' @noRd
 parse_jobs_json <- function(.json) {
   if (!length(.json$jobs)) {
     empty <- tibble::tibble(
@@ -57,9 +70,16 @@ parse_jobs_json <- function(.json) {
   purrr::list_rbind(purrr::map(.json$jobs, parse_job_to_row))
 }
 
-#' get slurm jobs
-#' @param user string of user id to filter results by
+#' Gets the jobs run on slurm as a tibble
+#'
+#' @param user optional user name to filter jobs only submitted by user
+#'
+#' @return a tibble containing the jobs submitted to slurm
 #' @export
+#'
+#' @examples \dontrun{
+#' get_slurm_jobs()
+#' }
 get_slurm_jobs <- function(user = NULL){
 
   cmd <- list(cmd = Sys.which("squeue"), args = "--json")

R/get-partitions.R

@@ -5,6 +5,8 @@ partition_cache <- new.env(parent = emptyenv())
 #' get list of each partition's number of CPUs and memory
 #'
 #' @return the raw partition-cpu-memory string output from `sinfo`
+#' @keywords internal
+#' @noRd
 run_sinfo <- function() {
   sinfobin <- Sys.which("sinfo")
   if (!nzchar(sinfobin)) {
@@ -29,9 +31,10 @@ run_sinfo <- function() {
 #'    [process_slurm_partitions()]
 #'
 #' @param cache optional argument to forgo caching
-#'
 #' @return the processed table of each partition's
 #'    number of CPUs and memory
+#' @keywords internal
+#' @noRd
 lookup_partitions_by_cpu <- function(cache = TRUE) {
   avail_cpus <- if(cache) {
     if (is.null(partition_cache[["run_sinfo"]])) {
@@ -57,6 +60,8 @@ lookup_partitions_by_cpu <- function(cache = TRUE) {
 #'
 #' @return the table such that the default partition will be first
 #'    and will have the asterisk removed
+#' @keywords internal
+#' @noRd
 process_slurm_partitions <- function(table){
   all_partitions <- table$PARTITION
   is_default_partition <- grepl('\\*$', x = all_partitions, )
@@ -69,12 +74,16 @@ process_slurm_partitions <- function(table){
   return(table)
 }
 
-
-#' get list of partition names for the given cluster
+#' Gets the available slurm partitions the user can use.
 #'
 #' @param cache optional argument to forgo caching
 #'
+#' @return vector of available partitions
 #' @export
+#'
+#' @examples \dontrun{
+#' get_slurm_partitions
+#' }
 get_slurm_partitions <- function(cache = TRUE) {
   table <- if (cache) {
     if (is.null(partition_cache[["partition_by_cpu"]])) {
@@ -105,6 +114,9 @@ get_slurm_partitions <- function(cache = TRUE) {
 #' @param cache optional argument to forgo caching
 #'
 #' @return string with suggestion upon [check_slurm_partitions()] error
+#'
+#' @keywords internal
+#' @noRd
 partition_advice <- function(ncpu, partition, avail_cpus_table, cache) {
 
   sorted_table <- avail_cpus_table %>% dplyr::filter(CPUS >= ncpu) %>%  dplyr::arrange(CPUS, MEMORY)
@@ -126,6 +138,9 @@ partition_advice <- function(ncpu, partition, avail_cpus_table, cache) {
 #' @param partition name of partition requested by user
 #' @param cache optional argument to forgo caching
 #'
+#' @keywords internal
+#' @noRd
+#'
 #' @examples \dontrun{
 #' check_slurm_partitions(17, "cpu2mem4gb")
 #' check_slurm_partitions(3, "cpu2mem4gb")

R/slurmtools-package.R → R/slurmtools.R

@@ -1,4 +1,28 @@
-#' @keywords internal
+#' slurmtools: An R package for easily submitting NONMEM jobs to slurm.
+#'
+#' This package aims to ease the submission and monitoring of NONMEM jobs running
+#' on slurm.
+#'
+#' @section submitting jobs:
+#' \itemize{
+#'  \item \code{\link{submit_nonmem_model}}: Submits a job to slurm
+#'  \item \code{\link{generate_nmm_config}}: Generates a NONMEMmonitor config
+#'  file
+#' }
+#'
+#' @section monitoring jobs:
+#' \itemize{
+#'  \item \code{\link{get_slurm_jobs}}: Gives a table of submitted jobs to slurm
+#'  that shows status and other information given with `squeue`
+#' }
+#'
+#' @section slurm partitions:
+#' \itemize{
+#'  \item \code{\link{get_slurm_partitions}}: Gives a vector of available
+#'  partitions a user can submit jobs to.
+#' }
+#'
+#' @name slurmtools
 "_PACKAGE"
 
 ## usethis namespace: start

_pkgdown.yml

@@ -12,17 +12,16 @@ navbar:
     left:
     - intro
     - reference
+    - articles
     right:
     - search
     - github
+    - lightswitch
   components:
     reference:
       text: Reference
       href: reference/index.html
-    github:
-      icon: fa-github fa-lg
-      href: https://github.com/a2-ai/slurmtools
-    intro:
+    articles:
       text: Get Started
       menu:
       - text: Running NONMEM
@@ -31,18 +30,18 @@ navbar:
         href: articles/custom-alerts.html
       - text: Slack Alerts
         href: articles/slack-alerts.html
+    github:
+      icon: fa-github fa-lg
+      href: https://github.com/a2-ai/slurmtools
 
 reference:
 - title: Data Processing Functions
   contents:
   - submit_nonmem_model
+  - generate_nmm_config
   - get_slurm_jobs
   - get_slurm_partitions
-  - check_slurm_partitions
-  - lookup_partitions_by_cpu
-  - partition_advice
-  - process_slurm_partitions
-  - run_sinfo
+  - slurmtools
 
 articles:
 - title: Vignettes