7  Documentation

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

7.1 R

We use the pkgdown package to create documentation for R packages, and host it on GitHub Pages. To get started with pkgdown, in R within the root of your package run usethis::use_pkgdown_github_pages() - 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 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.

7.1.1 WILDS pkgdown template

We are planning to have a WILDS specific pkgdown “package template” (see pkgdown docs 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:

template:
  package: wildstemplate

For now just use the default theme that pkgdown provides.

7.2 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:

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

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.

7.3 Guidelines

  • README:
    • All repositories must have a README.md file.
    • All repositories must have a project 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: “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 status projects should have:
    • a README that describes what the software does and how to install it. At the Experimental level and above, all functions should have accompanying docstrings (in the case of Python), roxygen2 comments (in the case of R), or equivalent function-level documentation. See Google’s style guide on Python docstrings and the R Packages chapter on function documentation.
  • Prototype status projects should have all of the above and:
    • a README that contains examples of how to use the software.
  • Stable status projects should have all the above and:
    • mature, fully-featured READMEs with badges for automated testing outcomes and software repository availability; detailed information about who the software is intended for, how it’s intended to be used, with fully-worked examples of how to install and use the software.
    • a standalone website that contains more detailed information about the software.