---
title: "How to update documentation"
output: github_document
vignette: |
  %\VignetteIndexEntry{How to update documentation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Roxygen2 and Pkgdown

Roxygen2-style comments are how we generate most content.

Example:

```
##' TileDB Cloud Manual Layer for Array Info
##'
##' This function shows array information on TileDB Cloud.
##'
##' Nominally you will first call \code{\link{login}}; if not, the results of
##' the last login at \code{~/.tiledb/cloud.json} will be used.
##'
##' @param namespace Like "TileDB-Inc"
##'
##' @param arrayname Like "quickstart_dense"
##'
##' @return A list of array properties
##' @export
array_info <- function(namespace, arrayname) {
  apiClientInstance <- get_api_client_instance()
  arrayApiInstance <- ArrayApi$new(apiClientInstance)
  # The $toJSON() converts from R6 class to R named list.
  # That in turn is nicely printable using str().
  arrayApiInstance$GetArrayMetadata(namespace, arrayname)$toJSON()
}

```

Notes:

* The first sentence will become the title -- used as one-line summary in the `docs/reference/index.html` reference page, and HTML/H1-style title when someone clicks through the link to the `docs/reference/name-of-the-function.html` details page.
* The second sentence will become summary text under the title in the `docs/reference/name-of-the-function.html` details page.
* The remaining bits will become the Details section in the `docs/reference/name-of-the-function.html` details page.
* Use `\code{\link{...}}` for in-package function references; use `\code{...}` for any other program text.
* The `@param` and `@return` are used for autogenerating the `docs/reference/name-of-the-function.html` details page.
* The `@export` tag is used by Roxygen2 to populate the `NAMESPACE` file. Note however that even non-exported functions will regardless appear in the `docs/reference/index.html` reference page. It's handy to name these with a leading `.` which matches a rule in our `_pkgdown.yml`, placing these functions in their own section at the bottom of the `docs/reference/index.html` reference page.
* The code autogenerated by OpenAPI already follows these conventions.

### _pkgdown.yml

See this repo's `_pkgdown.yml` for the `reference` and `articles` syntax which allow us to control section-ordering for reference and articles (vignettes).

The rule in the `reference` section is that items starting with `a-z` are manual-layer functions; those starting with `A-Z` are OpenAPI-autogen functions/classes; those starting with `.` are package-internal. As long as you follow these naming conventions for the code you write, you shouldn't need to modify `_pkgdown.yml` when you write new functions.

For new articles (vignettes), by contrast, you will need to add the information for your new vignette to `_pkgdown.yml`.

## Build steps

After `install.packages("roxygen2")` and `install.packages("pkgdown")` you should do `roxygen2::roxygenise()`. These outputs go into source control.

You can optionally do `pkgdown::build_site` and `open docs/index.html` to preview HTML locally and check that the rendering is as desired, but, be sure not to commit any of these outputs to source control.

How this works:

* On [https://github.com/TileDB-Inc/TileDB-Cloud-R/pull/103](https://github.com/TileDB-Inc/TileDB-Cloud-R/pull/103) we did a one-time `usethis::use_github_action("pkgdown")` which created `.github/workflows/pkgdown.yaml` and `.github/.gitignore`.
* In this repo's Settings -> Pages in GitHub we set up GitHub Pages to publish from the root directory on branch `gh-pages`, which is what the YAML from the previous bullet provides.
* This populates https://tiledb-inc.github.io/TileDB-Cloud-R/.

## Publishing

See [HowToRelease.md](./HowToRelease.md).