docs: add documentation

.Rbuildignore

@@ -15,3 +15,14 @@
 ^data/nursery\.arff$
 ^data/charity\.dta$
 ^prepare_to_submit_to_CRAN\.R$
+^pkgdown$
+^index\.md$
+^examples\.md$
+^installation\.md$
+^supports\.md$
+^welcome\.md$
+^\.vscode$
+^.*\.swp$
+^\.Rdata$
+^doc$
+^Meta$

.github/workflows/R-CMD-check.yaml

@@ -1,65 +1,49 @@
-# 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:
     branches: [main, master]
   pull_request:
     branches: [main, master]
-
 name: R-CMD-check
-
 jobs:
   R-CMD-check:
     runs-on: ${{ matrix.os }}
-
     name: ${{ matrix.os }} (${{ matrix.r }})
-
     strategy:
       fail-fast: false
       matrix:
         include:
-
-          # default everything
-          - {os: 'ubuntu-latest', python: '3.13', r: 'release'}
-          - {os: 'windows-latest', python: '3.13', r: 'release'}
-          - {os: 'macOS-latest', python: '3.13', r: 'release'}
-
-          # older R versions
-          - {os: 'ubuntu-latest', python: '3.9', r: 'oldrel-1'}
-          - {os: 'ubuntu-latest', python: '3.9', r: 'oldrel-2'}
-          - {os: 'ubuntu-latest', python: '3.9', r: 'oldrel-3'}
-
+          - { os: "ubuntu-latest", python: "3.13", r: "release" }
+          - { os: "windows-latest", python: "3.13", r: "release" }
+          - { os: "macOS-latest", python: "3.13", r: "release" }
+          - { os: "ubuntu-latest", python: "3.10", r: "oldrel-1" }
+          - { os: "ubuntu-latest", python: "3.10", r: "oldrel-2" }
+          - { os: "ubuntu-latest", python: "3.10", r: "oldrel-3" }
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
       R_KEEP_PKG_SOURCE: yes
-      # set matplotlib backend because Windows CI errors with:
-      # "This probably means that Tcl wasn't installed properly."
-      MPLBACKEND: Agg  # https://github.com/orgs/community/discussions/26434
-
+      MPLBACKEND: Agg
     steps:
       - name: Checkout ACRO
-        uses: actions/checkout@v5
-
+        uses: actions/checkout@v4
       - name: Setup Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python }}
-
       - name: Setup pandoc
         uses: r-lib/actions/setup-pandoc@v2
-
       - name: Setup R
         uses: r-lib/actions/setup-r@v2
         with:
           r-version: ${{ matrix.r }}
 
+      - name: Install Python ACRO
+        run: python -m pip install acro
+
       - name: Install R dependencies
         uses: r-lib/actions/setup-r-dependencies@v2
         with:
           extra-packages: any::rcmdcheck
           needs: check
-
       - name: Check R Package
         uses: r-lib/actions/check-r-package@v2
         with:

.github/workflows/pkgdown.yaml

@@ -14,12 +14,6 @@ jobs:
   pkgdown:
     runs-on: ubuntu-latest
 
-    concurrency:  # restrict concurrency for non-PR jobs
-      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
-
-    env:
-      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-
     steps:
       - name: Checkout
         uses: actions/checkout@v5

.gitignore

@@ -148,3 +148,6 @@ stata/various_stata_development__files
 # test output
 /outputs/
 /test.xlsx
+inst/doc
+/doc/
+/Meta/

.pre-commit-config.yaml

@@ -34,7 +34,8 @@ repos:
           (?x)^(
             .*\.txt|
             .*\.ipynb|
-            .*\.html
+            .*\.html|
+            docs/deps/.*
           )$
 
   # Format R files

DESCRIPTION

@@ -13,7 +13,7 @@ Description: A Tool for Semi-Automating the Statistical Disclosure Control of Re
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3
 SystemRequirements: Python (>= 3.10)
 Imports:
     reticulate,
@@ -23,9 +23,12 @@ Depends:
     R (>= 2.10)
 LazyData: true
 Suggests:
+    knitr,
+    rmarkdown,
     spelling,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 Language: en-US
 URL: https://github.com/AI-SDC/ACRO-R
 BugReports: https://github.com/AI-SDC/ACRO-R/issues
+VignetteBuilder: knitr

R/create_virtualenv.R

@@ -2,20 +2,29 @@ acro_venv <- "r-acro"
 acro_package <- "acro==0.4.11"
 python_version <- ">=3.10"
 
-
 #' Install acro
 #'
 #' @param envname the name of the Python virtual environment
+#' @param python the path to Python executable
 #' @param ... Any other parameters.
 #'
 #' @return No return value, called for side effects
+install_acro <- function(envname = "r-acro", python = NULL, ...) {
+  # Get Python executable if not provided
+  if (is.null(python)) {
+    python <- Sys.which("python3")
+    if (python == "") {
+      python <- Sys.which("python") # nocov
+      if (python == "") { # nocov
+        stop("Python not found in PATH. Please ensure Python is installed and accessible.") # nocov
+      } # nocov
+    }
+  }
 
-
-install_acro <- function(envname = "r-acro", ...) {
   # create Python virtual environment
   reticulate::virtualenv_create(
     envname = envname,
-    version = python_version,
+    python = python,
     force = TRUE,
     packages = NULL
   )
@@ -29,11 +38,16 @@ install_acro <- function(envname = "r-acro", ...) {
 #' @param ... Any other parameters.
 #'
 #' @return No return value, called for side effects
-
 create_virtualenv <- function(...) {
+  # Get Python executable path
+  python_path <- Sys.which("python3")
+  if (python_path == "") {
+    python_path <- Sys.which("python") # nocov
+  }
+
   # ensure a virtual environment exists
   if (!reticulate::virtualenv_exists(acro_venv)) {
-    install_acro(envname = acro_venv)
+    install_acro(envname = acro_venv, python = python_path)
   }
 
   # activate virtual environment

_pkgdown.yml

@@ -1,5 +1,27 @@
----
-url: https://AI-SDC.github.io/ACRO-R/
 template:
+  light-switch: true
   bootstrap: 5
-...
+  bslib:
+    primary: "#0051a5"
+
+navbar:
+  structure:
+    left: [home, reference, welcome, supports, installation, examples]
+    right: [search, github, lightswitch]
+  left:
+  - text: "Home"
+    href: index.html
+  - text: "Reference"
+    href: reference/index.html
+  - text: "Welcome to ACRO-R"
+    href: welcome.html
+  - text: "What ACRO-R Supports"
+    href: supports.html
+  - text: "Installation"
+    href: installation.html
+  - text: "Examples"
+    href: examples.html
+  right:
+  - icon: fab-github
+    href: https://github.com/AI-SDC/ACRO-R
+    aria-label: GitHub

inst/WORDLIST

@@ -2,27 +2,40 @@ ADR
 Acknowledgement
 Analytics
 EPSRC
+GPLv
 GRAIMATTER
 HDR
 Initialise
 Karnofsky
 MRC
 MyBinder
+NK
+PyPI
 RStudio
 SACRO
 SDC
+Scalable
+TRE
 Xplore
 auditable
+btn
 codecov
+crosstab
 disclosive
+finalise
 github
 https
 initialised
 json
+mitigations
 numpy
 openml
+organisation
 pre
 programme
+sacro
 scipy
+sm
+statsmodels
 www
 xlsx

inst/examples.md

@@ -0,0 +1,40 @@
+# Examples
+
+## Interactive Notebook
+
+For comprehensive examples and tutorials, see our interactive R notebook:
+
+[Example Notebook](articles/example-notebook.html)
+
+## Quick Start Examples
+
+### Basic Usage
+
+```r
+library("acro")
+
+# Initialize ACRO
+acro_init(suppress = TRUE)
+
+# Your analysis code here
+# ACRO will automatically check outputs for disclosure risks
+```
+
+### Creating Safe Tables
+
+```r
+# Example of creating a cross-tabulation with ACRO
+result <- acro_crosstab(data$variable1, data$variable2)
+
+# ACRO automatically applies disclosure control
+print(result)
+```
+
+### Finalizing Your Session
+
+```r
+# When you're done with your analysis
+acro_finalise()
+```
+
+For more detailed examples and use cases, please refer to the [Example Notebook](articles/example-notebook.html).

inst/index.md

@@ -0,0 +1,49 @@
+<img src="man/figures/SACRO_Logo_final.png" alt="Alt Text" width="20%">
+
+## AI-SDC Family Tools
+
+| **ACRO (Python)**                                                                                                                                                                                                                                                                                                               | **SACRO-ML**                                                                                                                                                                                                                                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Statistical Disclosure Control for Python** <br />Tools for the Semi-Automatic Checking of Research Outputs. Drop-in replacements for common analysis commands with built-in privacy protection.<br />[Statistical Analysis](https://sacro-tools.org/introduction.html){.btn .btn-acro .btn-sm} | **Machine Learning Privacy Tools** <br />Collection of tools and resources for managing the statistical disclosure control of trained machine learning models.<br />[Learn More](https://SACRO-ML.sacro-tools.org/introduction.html){.btn .btn-sacro-ml .btn-sm}                 |
+| **ACRO-R**                                                                                                                                                                                                                                                                                                                      | **SACRO-Viewer**                                                                                                                                                                                                                                                                                          |
+| **R Package Integration** <br />R-language interface for the Python ACRO library, providing familiar R syntax for statistical disclosure control.<br />[R Integration](reference/index.html){.btn .btn-acro-r .btn-sm}                                                     | **Graphical User Interface** <br />A graphical user interface for fast, secure and effective output checking, which can work in any TRE (Trusted Research Environment).<br />[View Docs](https://SACRO-Viewer.sacro-tools.org/introduction.html){.btn .btn-sacro-viewer .btn-sm} |
+
+## ACRO-R: Statistical Disclosure Control
+
+ACRO is a free and open source tool that supports the semi-automated checking of research outputs (SACRO) for privacy disclosure within secure data environments. SACRO is a framework that applies best-practice principles-based statistical disclosure control (SDC) techniques on-the-fly as researchers conduct their analysis. SACRO is designed to assist human checkers rather than seeking to replace them as with current automated rules-based approaches.
+
+## What is ACRO-R?
+
+ACRO implements a principles-based statistical disclosure control (SDC) methodology that:
+
+* Automatically identifies potentially disclosive outputs
+* Applies optional disclosure mitigation strategies
+* Reports reasons for applying SDC
+* Produces summary documents for output checkers
+
+## Core Features
+
+### Semi-Automated Disclosure Checking
+
+* **Drop-in replacements** for common Python analysis commands (pandas, statsmodels, etc.) with configurable disclosure checks
+* **Automated sensitivity tests** : frequency thresholds, dominance (p%, NK rules, etc.), residual degrees-of-freedom checks
+* **Optional mitigations** : suppression, rounding, and more to come
+* **Session management** : track, rename, comment, remove, add exceptions, and finalise reports
+* **Configurable risk parameters** via YAML files
+* **Generates auditable reports** in JSON or Excel
+
+### Design Principles
+
+* **Free and open source** under MIT (ACRO) / GPLv3 (SACRO Viewer)
+* **Easy to install** via PyPI, CRAN, or GitHub; cross-platform (Linux, macOS, Windows)
+* **Familiar APIs** - same function signatures as native commands: acro.crosstab mirrors pandas.crosstab, etc.
+* **Comprehensive coverage** - tables, regressions, histograms, survival plots, etc.
+* **Transparent & auditable** - clear reports, stored queries, designed for human-checkers
+* **Configurable & extensible** - organisation-defined disclosure rules, multi-language support
+* **Scalable** - lightweight, session-based, local execution
+
+## Getting Started
+
+| **Install**                                                                                                        | **Learn**                                                                                          | **Reference**                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Get ACRO-R installed and configured in your environment<br />[Install Guide](articles/installation.html){.btn .btn-primary} | Explore tutorials and examples for common use cases<br />[Examples](articles/index.html){.btn .btn-primary} | Complete API documentation and function reference<br />[API Docs](reference/index.html){.btn .btn-primary} |