Create pkgdown docs (#13)

* Fixed the parsing of the env files

* update changelog

* Do not complain when foreign keys are not found in a record, but also do not complain when they are

* rerender README

* update package description

* initialise pkgdown

* update changelog

* add vignettes

* update description

* extend documentation

* run styler

* create tempdir in homedir

* alternative approach

* ignore lintr in mermaid blocks

* fix r cmd check action

* fix ga

* add dependabot

* attempt to fix by installing rdpack

* use pkgdown's ga

* another attempt

* temporarily remove usage

* revert changes to r cmd check

* add pkgdown ci

* update changelog

* remove docs folder

.Rbuildignore

@@ -7,3 +7,6 @@
 ^CHANGELOG\.md$
 ^README\.qmd$
 ^docs$
+^_pkgdown\.yml$
+^pkgdown$
+^vignettes/*_files$

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"

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

@@ -20,11 +20,11 @@ jobs:
       fail-fast: false
       matrix:
         config:
-          - {os: macos-latest,   r: 'release'}
-          - {os: windows-latest, r: 'release'}
-          - {os: ubuntu-latest,  r: 'devel', http-user-agent: 'release'}
-          - {os: ubuntu-latest,  r: 'release'}
-          - {os: ubuntu-latest,  r: 'oldrel-1'}
+          - { os: macos-latest, r: "release" }
+          - { os: windows-latest, r: "release" }
+          - { os: ubuntu-latest, r: "devel", http-user-agent: "release" }
+          - { os: ubuntu-latest, r: "release" }
+          - { os: ubuntu-latest, r: "oldrel-1" }
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
@@ -33,8 +33,17 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # - name: Install lamin-cli
+      #   env:
+      #     LAMIN_API_KEY: ${{ secrets.LAMIN_API_KEY }}
+      #   run: |
+      #     pip install lamin-cli
+      #     lamin login
+
       - uses: r-lib/actions/setup-pandoc@v2
 
+      - uses: r-lib/actions/setup-tinytex@v2
+
       - uses: r-lib/actions/setup-r@v2
         with:
           r-version: ${{ matrix.config.r }}

.github/workflows/pkgdown.yaml

@@ -0,0 +1,57 @@
+# 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]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: pkgdown.yaml
+
+permissions: read-all
+
+jobs:
+  pkgdown:
+    runs-on: ubuntu-latest
+    # Only restrict concurrency for non-PR jobs
+    concurrency:
+      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::pkgdown, local::.
+          needs: website
+
+      # - name: Install lamin-cli
+      #   env:
+      #     LAMIN_API_KEY: ${{ secrets.LAMIN_API_KEY }}
+      #   run: |
+      #     pip install lamin-cli
+      #     lamin login
+
+      - name: Build site
+        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+        shell: Rscript {0}
+
+      - name: Deploy to GitHub pages 🚀
+        if: github.event_name != 'pull_request'
+        uses: JamesIves/[email protected]
+        with:
+          clean: false
+          branch: gh-pages
+          folder: docs

.gitignore

@@ -1,2 +1,3 @@
 .Rproj.user
 experiments
+docs

CHANGELOG.md

@@ -6,6 +6,8 @@
 
 * Read user settings from env file created by lamin Python package (PR #2, PR #8).
 
+* Render a pkgdown website (PR #13).
+
 ## MAJOR CHANGES
 
 * Refactored the internal class data structures for better modularity and extensibility (PR #8).
@@ -17,7 +19,15 @@
 
 ## MINOR CHANGES
 
-* Update `README` with new set up instructions and simplify (PR #14)
+* Update `README` with new set up instructions and simplify (PR #14).
+
+* Do not complain when foreign keys are not found in a record, but also do not complain when they are (PR #13).
+
+* Further simplify the `README`, and move the detailed usage description to a separate vignette (PR #13).
+
+* Add a `pkgdown` website to the project (PR #13).
+
+* Generate vignettes using Quarto (PR #13).
 
 ## BUG FIXES
 

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: laminr
 Title: LaminDB interface in R
-Version: 0.0.0.9000
+Version: 0.1.0.9000
 Authors@R:
     c(person("Robrecht", "Cannoodt",
         role = c("aut", "cre"),
@@ -13,7 +13,7 @@ License: Apache License (>= 2)
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
-URL: https://github.com/laminlabs/laminr
+URL: https://laminr.lamin.ai, https://github.com/laminlabs/laminr
 BugReports: https://github.com/laminlabs/laminr/issues
 Depends:
     R (>= 4.0.0)
@@ -25,4 +25,6 @@ Imports:
     R6
 Suggests:
     anndata,
+    quarto,
     s3 (>= 1.1.0)
+VignetteBuilder: quarto

NAMESPACE

@@ -11,6 +11,7 @@ importFrom(httr,add_headers)
 importFrom(httr,content)
 importFrom(jsonlite,toJSON)
 importFrom(purrr,discard)
+importFrom(purrr,keep)
 importFrom(purrr,list_flatten)
 importFrom(purrr,map)
 importFrom(purrr,map2)

R/Record.R

@@ -65,11 +65,12 @@ Record <- R6::R6Class( # nolint object_name_linter
       private$.api <- api
       private$.data <- data
 
-      column_names <- map(registry$get_fields(), "column_name") |>
-        unlist() |>
+      expected_fields <-
+        registry$get_fields() |>
+        discard(~ is.null(.x$column_name)) |>
+        map_chr("column_name") |>
         unname()
-
-      unexpected_fields <- setdiff(names(data), column_names)
+      unexpected_fields <- setdiff(names(data), expected_fields)
       if (length(unexpected_fields) > 0) {
         cli_warn(
           paste0(
@@ -79,7 +80,12 @@ Record <- R6::R6Class( # nolint object_name_linter
         )
       }
 
-      missing_fields <- setdiff(column_names, names(data))
+      required_fields <-
+        registry$get_fields() |>
+        keep(~ is.null(.x$relation_type)) |>
+        map_chr("column_name") |>
+        unname()
+      missing_fields <- setdiff(required_fields, names(data))
       if (length(missing_fields) > 0) {
         cli_warn(
           paste0(

R/Registry.R

@@ -49,7 +49,7 @@ Registry <- R6::R6Class( # nolint object_name_linter
       )
     },
     #' Get a record by ID or UID.
-    get = function(id_or_uid, include_foreign_keys = TRUE, verbose = FALSE) {
+    get = function(id_or_uid, include_foreign_keys = FALSE, verbose = FALSE) {
       data <- private$.api$get_record(
         module_name = private$.module$name,
         registry_name = private$.registry_name,

R/connect.R

@@ -3,8 +3,13 @@
 
 #' Connect to instance
 #'
+#' Note that prior to connecting to an instance, you need to authenticate with
+#' `lamin login`. If no slug is provided, the default instance is loaded, which is
+#' set by running `lamin load <slug>`.
+#'
 #' @param slug The instance slug `account_handle/instance_name` or URL.
 #'   If the instance is owned by you, it suffices to pass the instance name.
+#'   If no slug is provided, the default instance is loaded.
 #'
 #' @export
 #'
@@ -14,9 +19,14 @@
 #' instance <- connect("laminlabs/cellxgene")
 #' instance
 #' }
-connect <- function(slug) {
+connect <- function(slug = NULL) {
   user_settings <- .settings_load__load_or_create_user_settings()
 
+  if (is.null(slug)) {
+    current_instance <- .settings_load__load_instance_settings()
+    slug <- paste0(current_instance$owner, "/", current_instance$name)
+  }
+
   owner_name <- .connect_get_owner_name_from_identifier(slug)
 
   instance_settings <- .connect_get_instance_settings(

R/laminr-package.R

@@ -5,6 +5,6 @@
 #' @importFrom cli cli_abort cli_warn cli_inform
 #' @importFrom R6 R6Class
 #' @importFrom httr GET POST content add_headers
-#' @importFrom purrr map map_chr map2 pmap set_names list_flatten transpose discard
+#' @importFrom purrr map map_chr map2 pmap set_names list_flatten transpose discard keep
 ## usethis namespace: end
 NULL