Merge pull request #60 from HighlanderLab/issue/58

Adding document GitHub action

Author: gregorgorjanc

.github/workflows/.gitignore

@@ -0,0 +1 @@
+*.html

.github/workflows/document.yaml

@@ -0,0 +1,47 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    paths: ["R/**"]
+
+name: document.yaml
+
+permissions: read-all
+
+jobs:
+  document:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup R
+        uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - name: Install dependencies
+        uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          working-directory: RcppTskit
+          extra-packages: any::roxygen2
+          needs: roxygen2
+
+      - name: Document
+        run: setwd("RcppTskit"); roxygen2::roxygenise()
+        shell: Rscript {0}
+
+      - name: Commit and push changes
+        run: |
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com"
+          git add man/\* NAMESPACE DESCRIPTION
+          git commit -m "Update documentation" || echo "No changes to commit"
+          git pull --ff-only
+          git push origin

.github/workflows/r-universe-check.yaml

@@ -1,15 +1,23 @@
-*.Rproj
+.DS_Store
 .Rproj.user
 .Rhistory
 .RData
 .Ruserdata
 .vscode
+*.Rproj
+RcppTskit/cran-comments.html
+RcppTskit/cran-comments_files/
+RcppTskit/**/.quarto/
+RcppTskit/inst/doc
 RcppTskit/src/*.o
 RcppTskit/src/tskit/*.o
 RcppTskit/src/*.so
 RcppTskit/src/*.dll*
 RcppTskit/src/Makevars
 RcppTskit/src/Makevars.win
+RcppTskit/vignettes/*.html
+RcppTskit/vignettes/*.R
+RcppTskit/vignettes/*_files/
+README.html
+README_files/
 test.trees
-.DS_Store
-*.html

.gitignore

@@ -0,0 +1,126 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at gregor.gorjanc@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][https://github.com/mozilla/inclusion].
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq>. Translations are available at <https://www.contributor-covenant.org/translations>.
+
+[homepage]: https://www.contributor-covenant.org

CODE_OF_CONDUCT.md

@@ -2,42 +2,57 @@
 
 ## Overview
 
-Tskit enables performant storage, manipulation, and analysis of ancestral
+`Tskit` enables performant storage, manipulation, and analysis of ancestral
 recombination graphs (ARGs) using succinct tree sequence encoding.
+The tree sequence encoding of an ARG is
+described in Wong et al. (2024) <doi:10.1093/genetics/iyae100>.
 See https://tskit.dev for project news, documentation, and tutorials.
-Tskit provides Python, C, and Rust APIs. The Python API can be called from R
-via the `reticulate` R package to seamlessly load and analyse a tree sequence,
-as described at https://tskit.dev/tutorials/RcppTskit.html.
+`Tskit` provides Python, C, and Rust application programming interfaces (APIs).
+The Python API can be called from R via the `reticulate` R package to
+seamlessly load and analyse a tree sequence, as described at
+https://tskit.dev/tutorials/RcppTskit.html.
 `RcppTskit` provides R access to the `tskit` C API for use cases where the
-`reticulate` approach is not optimal. For example, for high-performance and
-low-level work with tree sequences. Currently, `RcppTskit` provides a very limited
+`reticulate` option is not optimal. For example, for high-performance and
+low-level work with tree sequences. Currently, `RcppTskit` provides a limited
 number of R functions due to the availability of extensive Python API and
-the `reticulate` approach.
+the `reticulate` option.
 
-See more details on the state of the tree sequence ecosystem and aims for
-`RcppTskit` in [RcppTskit/inst/STATE_and_AIMS.md](RcppTskit/inst/STATE_and_AIMS.md),
-including examples on how to use it on its own or to develop new R packages.
-
-TODO: Think how to best point to use cases. Probably best to point to vignette and pkgdown!?
-      https://github.com/HighlanderLab/RcppTskit/issues/10
+See more details on the state of the tree sequence ecosystem and aims of
+`RcppTskit` in [the introduction vignette](https://highlanderlab.r-universe.dev/articles/RcppTskit/RcppTskit_intro.html) ([source](RcppTskit/vignettes/RcppTskit_intro.qmd)).
+The vignette also shows examples on how to use `RcppTskit` on its own or
+to develop new R packages.
 
 ## Status
 
 <!-- badges: start -->
 
-[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) <!-- Row 1, Col 1 --> [![Development](https://img.shields.io/badge/development-active-blue.svg)](https://img.shields.io/badge/development-active-blue.svg) <!-- Row 1, Col 2 --> [![Licence](https://img.shields.io/badge/licence-MIT-blue.svg)](https://opensource.org/licenses/MIT) <!-- Row 1, Col 3 -->
+<!-- Row 1 -->
+General: [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) <!-- Col-1-End -->
+[![Development](https://img.shields.io/badge/development-active-blue.svg)](https://img.shields.io/badge/development-active-blue.svg) <!-- Col-2-End -->
+[![Licence](https://img.shields.io/badge/licence-MIT-blue.svg)](https://opensource.org/licenses/MIT) <!-- Col-3-End -->
+
+<!-- Row 2 -->
+Release: [![CRAN version](https://www.r-pkg.org/badges/version/RcppTskit)](https://CRAN.R-project.org/package=RcppTskit) <!-- Col-1-End -->
+[![Downloads - total](https://cranlogs.r-pkg.org/badges/grand-total/RcppTskit)](https://cranlogs.r-pkg.org/badges/grand-total/RcppTskit) <!-- Col-2-End -->
+![GitHub version (main)](https://img.shields.io/github/r-package/v/HighlanderLab/RcppTskit/main?filename=RcppTskit%2FDESCRIPTION&label=Github) <!-- Col-3-End -->
 
-<!-- line break 1 -->
-[![CRAN version](https://www.r-pkg.org/badges/version/RcppTskit)](https://CRAN.R-project.org/package=RcppTskit) <!-- Row 2, Col 1 --> ![GitHub version (main)](https://img.shields.io/github/r-package/v/HighlanderLab/RcppTskit/main?filename=RcppTskit%2FDESCRIPTION&label=Github) <!-- Row 2, Col 2 --> [![Downloads - total](https://cranlogs.r-pkg.org/badges/grand-total/RcppTskit)](https://cranlogs.r-pkg.org/badges/grand-total/RcppTskit) <!-- Row 2, Col 3 -->
+<!-- Row 3 -->
+R CMD checks: [![CRAN](https://cranchecks.info/badges/summary/RcppTskit?label=CRAN)](https://cran.r-project.org/web/checks/check_results_RcppTskit.html) <!-- Col-1-End -->
+[![R universe](https://highlanderlab.r-universe.dev/RcppTskit/badges/checks?label=R-universe)](https://highlanderlab.r-universe.dev/RcppTskit) <!-- Col-2-End -->
+[![GitHub](https://img.shields.io/github/actions/workflow/status/HighlanderLab/RcppTskit/R-CMD-check.yaml?label=GitHub)](https://github.com/HighlanderLab/RcppTskit/actions/workflows/R-CMD-check.yaml) <!-- Col-3-End -->
 
-<!-- line break 2 -->
-[![CRAN R CMD check](https://cranchecks.info/badges/summary/RcppTskit)](https://cran.r-project.org/web/checks/check_results_RcppTskit.html) <!-- Row 3, Col 1 --> ![GitHub R CMD check](https://img.shields.io/github/actions/workflow/status/HighlanderLab/RcppTskit/R-CMD-check.yaml?label=GitHub%20R%20CMD%20check) <!-- Row 3, Col 2 --> [![Codecov test coverage](https://codecov.io/gh/HighlanderLab/RcppTskit/graph/badge.svg)](https://app.codecov.io/gh/HighlanderLab/RcppTskit) <!-- Row 3, Col 3 -->
+<!-- Row 4 -->
+Code quality: [![Codecov test coverage](https://codecov.io/gh/HighlanderLab/RcppTskit/graph/badge.svg)](https://app.codecov.io/gh/HighlanderLab/RcppTskit) <!-- Col-1-End -->
 
 <!-- badges: end -->
 
 ## Contents
 
-  * `extern` - Git submodule for `tskit` and instructions on obtaining the latest version and copying the `tskit` C code into `RcppTskit` directory. `extern` is saved outside of the `RcppTskit` directory because `R CMD CHECK` complains otherwise.
+  * `extern` - Git submodule for `tskit` and instructions on
+    obtaining the latest version and copying the `tskit` C code into
+    `RcppTskit` directory.
+    `extern` is saved outside of the `RcppTskit` directory
+    because `R CMD CHECK` complains otherwise (even with `.Rbuildignore`).
 
   * `RcppTskit` - R package `RcppTskit`.
 
@@ -67,33 +82,39 @@ https://mac.r-project.org/tools for macOS tools.
 ```
 # install.packages("remotes") # If you don't have it already
 
-# Release (TODO)
+# Release
 # TODO: Tag a release #15
 #       https://github.com/HighlanderLab/RcppTskit/issues/15
 # remotes::install_github("HighlanderLab/RcppTskit/RcppTskit")
 
 # Main branch
-remotes::install_github("HighlanderLab/RcppTskit/RcppTskit")
+remotes::install_github("HighlanderLab/RcppTskit/RcppTskit@main")
 
 # Development branch
-# TODO: Create a devel branch #16
-#       https://github.com/HighlanderLab/RcppTskit/issues/16
-# remotes::install_github("HighlanderLab/RcppTskit/RcppTskit@devel")
+remotes::install_github("HighlanderLab/RcppTskit/RcppTskit@devel")
 ```
 
 ## Development
 
+### Code of Conduct
+
+Please note that the `RcppTskit` project is released with a
+[Contributor Code of Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html).
+By contributing to this project, you agree to abide by its terms.
+
 ### Clone
 
-First clone the repository:
+First clone the repository and step into the directory:
 
 ```
 git clone https://github.com/HighlanderLab/RcppTskit.git
+cd RcppTskit
 ```
 
 ### Pre-commit install
 
-We use [pre-commit](https://pre-commit.com) hooks to ensure code quality. Specifically, we use:
+We use [pre-commit](https://pre-commit.com) hooks to ensure code quality.
+Specifically, we use:
 * [air](https://github.com/posit-dev/air) to format R code,
 * [jarl](https://github.com/etiennebacher/jarl) to lint R code,
 * [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to format C/C++ code, and
@@ -111,7 +132,8 @@ If you plan to update `tskit`, follow instructions in `extern/README.md`.
 
 ### RcppTskit
 
-Then open `RcppTskit` package directory in your favourite R IDE (Positron, RStudio, text-editor-of-your-choice, etc.) and implement your changes.
+Then open `RcppTskit` package directory in your favourite R IDE
+(Positron, RStudio, text-editor-of-your-choice, etc.) and implement your changes.
 
 You should routinely check your changes (in R):
 
@@ -161,6 +183,8 @@ pre-commit run --all-files
 
 ### Continuous integration
 
-We use Github Actions to run continuous integration (CI) checks on each push and pull request. Specifically, we run:
+We use Github Actions to run continuous integration (CI) checks
+on each push and pull request.
+Specifically, we run:
 * [R CMD check](.github/workflows/R-CMD-check.yaml) on multiple platforms and
 * [covr test coverage](.github/workflows/covr.yaml).

README.md

@@ -9,8 +9,19 @@
 ^\.clang-format$
 ^\.covrignore$
 ^\.github$
-^pkg_dev_notes\.md$
 ^codecov\.yaml$
-^notes_pkg_dev\.Rmd$
+^cran-comments\.md$
+^cran-comments\.html$
+^cran-comments_files$
 ^inst/examples/create_test\.trees\.R$
 ^inst/examples/create_test\.trees\.py$
+^inst/examples/explore_reticulate\.R$
+^inst/examples/explore_slendr\.R$
+^LICENSE.md$
+^notes_pkg_dev\.Rmd$
+^pkg_dev_notes\.md$
+^tests/testthat/_snaps$
+^tools/clang-tidy\.py$
+^vignettes/\.quarto$
+^vignettes/*_files$
+^\.\.$