packagedocs.qmd

# Documentation {{< iconify fa6-solid book >}} {#sec-docs}

All formally supported WILDS R and Python packages should have package documentation.

## R {#sec-docs-r}

We use the [pkgdown][] package to create documentation for R packages, and host it on [GitHub Pages][ghpages]. To get started with `pkgdown`, in R within the root of your package run [usethis::use_pkgdown_github_pages()](https://usethis.r-lib.org/reference/use_pkgdown.html) - it will set up a `_pkgdown.yml` file in the root of your repo used to configure `pkgdown`, and add a `.github/workflows/publish.yml` file to build the package documentation on each push, pull request, or release. See [pkgdown documentation][pkgdown] for details on configuring documentation.

After pushing the above changes up to your repository, go to the Actions tab and you should see the new `publish` action running. It will build and then deploy the rendered package docs. The URL for your docs will vary depending on the GitHub organization your repository lives within. For WILDS, the base URL is `https://getwilds.org`. If your package is in the WILDS org (at `https://github.com/getwilds`) your package (named `mypkg`) docs would live at `https://getwilds.org/mypkg`.

You can also build `pkgdown` docs locally - after running `usethis::use_pkgdown()` or `usethis::use_pkgdown_github_pages()` - by running `pkgdown::build_site()`. If you run `build_site()` within RStudio it should open up your site in your default browser, but may not do so if you run in a terminal. You can open the site in your browser by navigating to and opening the file `docs/index.html` within your repo.

### WILDS pkgdown template

We are planning to have a WILDS specific `pkgdown` "package template" (see [pkgdown docs][pkgdowntemp] for what this means) - but it's not ready to use yet. When it is ready, you will be able to specify our template like:

```yml
template:
  package: wildstemplate
```

For now just use the default theme that `pkgdown` provides.

## Python {#sec-docs-python}

Just like there's a variety of ways to do packing in Python there's a variety of documentation options. Two of the well known options are:

- [Sphinx][] - been around longer, uses [reStructuredText][rst]
- [MkDocs][] - newcomer, uses [Markdown][md]
- [quartodoc][] - another newcomer, also uses [Markdown][md] (built on [Quarto](https://quarto.org/))

For any of the options above, they can be hosted in many places, including [GitHub Pages][ghpages] and [ReadTheDocs][rtd].

`Sphinx` and `MkDocs` are less automatic relative to `pkgdown`, so just be prepared for a bit more manual work. We're not familiar with `quartodoc`, so not sure where it falls on the continuum between easy to use and hard to use.

## Guidelines

- README:
  - {{< var rule-badge >}} {{< var rules.readme >}}
  - {{< var rule-badge >}} {{< var rules.status-badge >}} (see below for badge specific guidelines).
  - This is most likely the first place potential users will interact with your package. Make sure the README clearly states what the package does, and how to get started.
- Examples: All user facing functions should have examples. Make sure to be careful about how examples are run if there's any sensitive data or connections to remote services.
- Vignettes: From the [R Packages book](https://r-pkgs.org/vignettes.html): "A vignette is a long-form guide to your package. Function documentation is great if you know the name of the function you need, but it’s useless otherwise. In contrast, a vignette can be framed around a target problem that your package is designed to solve. The vignette format is perfect for showing a workflow that solves that particular problem, start to finish. Vignettes afford you different opportunities than help topics: you have much more control over the integration of code and prose and it’s a better setting for showing how multiple functions work together."

Badge specific guidelines

- [**Experimental**](#statuses) status projects should have:
  - {{< var rule-badge >}} {{< var rules.readme-basic >}} See Google’s style guide on [Python docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) and the R Packages chapter on [function documentation](https://r-pkgs.org/man.html).
- [**Prototype**](#statuses) status projects should have all of the above and:
  - {{< var rule-badge >}} {{< var rules.readme-egs >}}
- [**Stable**](#statuses) status projects should have all the above and:
  - {{< var rule-badge >}} {{< var rules.readme-detailed >}}
  - {{< var rule-badge >}} {{< var rules.docs-website >}}


[pkgdown]: https://pkgdown.r-lib.org/
[rtd]: https://about.readthedocs.com/
[Sphinx]: https://www.sphinx-doc.org/
[mkdocs]: https://www.mkdocs.org/
[pkgdowntemp]: https://pkgdown.r-lib.org/articles/customise.html#template-packages
[ghpages]: https://pages.github.com/
[rst]: https://docutils.sourceforge.io/rst.html
[md]: https://www.markdownguide.org/
[quartodoc]: https://pypi.org/project/quartodoc/