doc: added doc return and example and other minor

.Rbuildignore

@@ -19,3 +19,4 @@
 ^vignettes/*_files$
 ^README\.Rmd$
 ^README\.html$
+^cran-comments\.md$

.github/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to condathis
+
+This outlines how to propose a change to condathis.
+For a detailed discussion on contributing to this and other tidyverse packages, please see the [development contributing guide](https://rstd.io/tidy-contrib) and our [code review principles](https://code-review.tidyverse.org/).
+
+## Fixing typos
+
+You can fix typos, spelling mistakes, or grammatical errors in the documentation directly using the GitHub web interface, as long as the changes are made in the _source_ file. 
+This generally means you'll need to edit [roxygen2 comments](https://roxygen2.r-lib.org/articles/roxygen2.html) in an `.R`, not a `.Rd` file. 
+You can find the `.R` file that generates the `.Rd` by reading the comment in the first line.
+
+## Bigger changes
+
+If you want to make a bigger change, it's a good idea to first file an issue and make sure someone from the team agrees that it’s needed. 
+If you’ve found a bug, please file an issue that illustrates the bug with a minimal 
+[reprex](https://www.tidyverse.org/help/#reprex) (this will also help you write a unit test, if needed).
+See our guide on [how to create a great issue](https://code-review.tidyverse.org/issues/) for more advice.
+
+### Pull request process
+
+*   Fork the package and clone onto your computer. If you haven't done this before, we recommend using `usethis::create_from_github("luciorq/condathis", fork = TRUE)`.
+
+*   Install all development dependencies with `devtools::install_dev_deps()`, and then make sure the package passes R CMD check by running `devtools::check()`. 
+    If R CMD check doesn't pass cleanly, it's a good idea to ask for help before continuing. 
+*   Create a Git branch for your pull request (PR). We recommend using `usethis::pr_init("brief-description-of-change")`.
+
+*   Make your changes, commit to git, and then create a PR by running `usethis::pr_push()`, and following the prompts in your browser.
+    The title of your PR should briefly describe the change.
+    The body of your PR should contain `Fixes #issue-number`.
+
+*  For user-facing changes, add a bullet to the top of `NEWS.md` (i.e. just below the first header). Follow the style described in <https://style.tidyverse.org/news.html>.
+
+### Code style
+
+*   New code should follow the tidyverse [style guide](https://style.tidyverse.org). 
+    You can use the [styler](https://CRAN.R-project.org/package=styler) package to apply these styles, but please don't restyle code that has nothing to do with your PR.  
+
+*  We use [roxygen2](https://cran.r-project.org/package=roxygen2), with [Markdown syntax](https://cran.r-project.org/web/packages/roxygen2/vignettes/rd-formatting.html), for documentation.  
+
+*  We use [testthat](https://cran.r-project.org/package=testthat) for unit tests. 
+   Contributions with test cases included are easier to accept.  
+
+## Code of Conduct
+
+Please note that the condathis project is released with a
+[Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this
+project you agree to abide by its terms.

DESCRIPTION

@@ -2,26 +2,17 @@ Package: condathis
 Title: Run Any CLI Tool on a Conda Environment
 Version: 0.0.6.9008
 Authors@R: c(
-    person(given = "Lucio",
-           family = "Queiroz",
-           role = c("aut", "cre", "cph"),
-           email = "[email protected]",
+    person("Lucio", "Queiroz", , "[email protected]", role = c("aut", "cre", "cph"),
            comment = c(ORCID = "0000-0002-6090-1834")),
-    person(given = "Claudio",
-           family = "Zanettini",
-           role = c("aut", "ctb"),
-           email = "[email protected]",
-           comment = c(ORCID = "0000-0001-5043-8033")
-    ))
-Description: Simplifies the execution of command line tools within isolated and
-    reproducible environments.
-    It enables users to effortlessly manage Conda environments,
-    execute command line tools, handle dependencies, and ensure reproducibility
-    in their data analysis workflows.
+    person("Claudio", "Zanettini", , "[email protected]", role = c("aut", "ctb"),
+           comment = c(ORCID = "0000-0001-5043-8033"))
+  )
+Description: Simplifies the execution of command line tools within
+    isolated and reproducible environments.  It enables users to
+    effortlessly manage Conda environments, execute command line tools,
+    handle dependencies, and ensure reproducibility in their data analysis
+    workflows.
 License: MIT + file LICENSE
-Encoding: UTF-8
-Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
 URL: https://github.com/luciorq/condathis
 BugReports: https://github.com/luciorq/condathis/issues
 Imports:
@@ -36,7 +27,10 @@ Imports:
     utils,
     withr
 Suggests:
-    testthat (>= 3.0.0),
     curl,
-    dplyr
+    dplyr,
+    testthat (>= 3.0.0)
 Config/testthat/edition: 3
+Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.3.2

R/create_env.R

@@ -36,7 +36,16 @@
 #'
 #' @param overwrite Logical. Should environment always be overwritten?
 #'     Defaults to `FALSE`.
-#'
+#' @return No value is returned; this function is used for its side effect of creating a conda environment.
+#' @examples
+#' \dontrun{
+#' # Create a Conda environment and install the CLI `fastqc` in it.
+#' condathis::create_env(packages = "fastqc==0.12.1",
+#'                       env_name = "fastqc_env",
+#'                       verbose = "output"
+#'                       )
+#' #> ! Environment fastqc_env succesfully created.
+#' }
 #' @export
 create_env <- function(
     packages = NULL,

R/env_exists.R

@@ -1,7 +1,17 @@
 #' Check If Environment Names Already exists
 #'
 #' @inheritParams create_env
-#'
+#' @return Boolean.
+#' @examples
+#' \dontrun{
+#' # Create the environment
+#' condathis::create_env(packages = "fastqc",
+#'                       env_name = "fastqc_env"
+#'                       )
+#' # Check if exists
+#' condathis::env_exists("fastqc_env")
+#' #> [1] TRUE
+#' }
 #' @export
 env_exists <- function(env_name = "condathis-env") {
   available_envs <- list_envs()

R/get_env_dir.R

@@ -4,7 +4,12 @@
 #'    **Note**: It retrieves the Path even if the environment is **not** created yet.
 #'
 #' @inheritParams create_env
-#'
+#' @return A character string indicating the path where environments will be created.
+#' @examples
+#' \dontrun{
+#' condathis::get_env_dir()
+#' #> /Users/myself/.local/share/condathis/envs/condathis-env
+#' }
 #' @export
 get_env_dir <- function(env_name = "condathis-env") {
   return(fs::path(get_install_dir(), "envs", env_name))

R/get_install_dir.R

@@ -15,9 +15,10 @@
 #' A character string representing the normalized, real path to the `condathis` data directory.
 #'
 #' @examples
-#' install_dir <- get_install_dir()
-#' print(install_dir)
-#'
+#' \dontrun{
+#' condathis::get_install_dir()
+#' #> /Users/myself/.local/share/condathis
+#' }
 #' @export
 get_install_dir <- function() {
   dir_path <- get_condathis_path()

R/get_sys_arch.R

@@ -1,4 +1,12 @@
 #' Return OS and CPU Architecture
+#'
+#' @return A character vector with one element indicating OS and CPU Architecture.
+#' @examples
+#' \dontrun{
+#' # Create a Conda environment with the CLI fastqc
+#' condathis::get_sys_arch()
+#' #> [1] "Darwin-x86_64"
+#' }
 #' @export
 get_sys_arch <- function() {
   os <- base::Sys.info()["sysname"]

R/install_micromamba.R

@@ -30,13 +30,13 @@
 #' @examples
 #' \dontrun{
 #' # Install the default version of Micromamba
-#' install_micromamba()
+#' condathis::install_micromamba()
 #'
 #' # Install a specific version of Micromamba
-#' install_micromamba(micromamba_version = "2.0.2-1")
+#' condathis::install_micromamba(micromamba_version = "2.0.2-1")
 #'
 #' # Force reinstallation of Micromamba
-#' install_micromamba(force = TRUE)
+#' condathis::install_micromamba(force = TRUE)
 #' }
 #'
 #' @export

R/install_packages.R

@@ -6,6 +6,17 @@
 #'
 #' @inheritParams create_env
 #'
+#' @return No value is returned; this function is used for its side effect of installing packages in a conda environment.
+#' @examples
+#' \dontrun{
+#' condathis::create_env(packages = "fastqc",
+#'                       env_name = "fastqc_env"
+#'                       )
+#' # Install the package `vim` in the `fastqc_env` environment.
+#' # It is not recommended to install multiple packages in the same environment,
+#  # as it defeats the purpose of isolation provided by separate environments.
+#' condathis::install_packages(packages = "vim", env_name = "fastqc_env")
+#' }
 #' @export
 install_packages <- function(packages,
                              env_name = "condathis-env",

R/list_envs.R

@@ -1,7 +1,20 @@
 #' List Installed Environments
 #'
 #' @inheritParams run
-#'
+#' @return Character vector of name of conda environment installed.
+#' @examples
+#' \dontrun{
+#' #'Create the environments
+#' condathis::create_env(packages = "fastqc",
+#'                       env_name = "fastqc_env"
+#'                       )
+#' condathis::create_env(packages = "samtool",
+#'                       env_name = "samtool_env"
+#'                       )
+#' # List environments
+#' condathis::list_envs()
+#' #> [1] "fastqc-env"  "samtools_env"
+#' }
 #' @export
 list_envs <- function(verbose = "silent") {
   env_root_dir <- get_install_dir()

R/list_packages.R

@@ -1,5 +1,28 @@
 #' List Packages Installed Inside Environment
 #' @inheritParams run
+#' @return A tibble containing all the packages installed in the specified environment,
+#' with the following columns:
+#' \describe{
+#'   \item{base_url}{The base URL of the package source.}
+#'   \item{build_number}{The build number of the package.}
+#'   \item{build_string}{The build string describing the package build details.}
+#'   \item{channel}{The channel from which the package was installed.}
+#'   \item{dist_name}{The distribution name of the package.}
+#'   \item{name}{The name of the package.}
+#'   \item{platform}{The platform for which the package is built.}
+#'   \item{version}{The version of the package.}
+#' }
+#' @examples
+#' \dontrun{
+#' # Creates a Conda environment with the CLI `fastqc`
+#' condathis::create_env(packages = "fastqc",
+#'                       env_name = "fastqc_env"
+#'                       )
+#' # Lists the packages in env `fastqc_env`
+#' dat <- condathis::list_packages("fastqc_env")
+#' dim(dat)
+#' #> [1] 34  8
+#' }
 #' @export
 list_packages <- function(env_name = "condathis-env", verbose = "silent") {
   px_res <- native_cmd(

R/remove_env.R

@@ -3,7 +3,14 @@
 #' Remove a Conda environment previously created by `create_env()`.
 #'
 #' @inheritParams create_env
-#'
+#' @return No value is returned; this function is used for its side effect of removing a conda environment.
+#' @examples
+#' \dontrun{
+#' condathis::create_env(packages = "fastqc,
+#'                       env_name = "fastqc_env",
+#'                       )
+#' condathis::remove_env(env_name = "fastqc_env)
+#' }
 #' @export
 remove_env <- function(env_name = "condathis-env",
                        verbose = "silent") {

R/run_bin.R

@@ -11,10 +11,10 @@
 #' \dontrun{
 #' # Example assumes that 'my_env' exists and contains 'python'
 #' # Run 'python' with a script in 'my_env' environment
-#' run_bin("python", "script.py", env_name = "my_env", verbose = "silent")
+#' condathis::run_bin("python", "script.py", env_name = "my_env", verbose = "silent")
 #'
 #' # Run 'ls' command with additional arguments
-#' run_bin("ls", "-la", env_name = "my_env")
+#' condathis::run_bin("ls", "-la", env_name = "my_env")
 #' }
 #'
 #' @export

condathis.Rproj

@@ -1,5 +1,4 @@
 Version: 1.0
-ProjectId: 9ddf74f2-3627-4d31-97aa-6a6d7606c524
 
 RestoreWorkspace: No
 SaveWorkspace: No

cran-comments.md

@@ -0,0 +1,5 @@
+## R CMD check results
+
+0 errors | 0 warnings | 1 note
+
+* This is a new release.