8 Documentation
All formally supported WILDS R and Python packages should have package documentation.
8.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.
8.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: wildstemplateFor now just use the default theme that pkgdown provides.
8.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:
- Sphinx - been around longer, uses reStructuredText
- MkDocs - newcomer, uses Markdown
- quartodoc - another newcomer, also uses Markdown (built on Quarto)
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.
8.3 Guidelines
- README:
-
-
- 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:
-
-
- Prototype status projects should have all of the above and:
-
-
- Stable status projects should have all the above and:
-
-
-