Create GHA workflow for altdoc (#122)

* init

* create skeleton

* remove the step setup_docs()

* use r2u, deal with mkdocs installation

* only install python if mkdocs used

* trigger CI

* rename .yml -> .yaml

* try to install locally

* typo

* fix freeze in future

* install quarto

* fix

* try to manually install quarto

* maybe don't need sudo?

* update comments

* create_workflow -> setup_workflow

* update template

* document

* better path handling

* docs

.github/workflows/altdoc.yaml

@@ -0,0 +1,59 @@
+# 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: altdoc
+
+concurrency:
+  group: altdoc-${{ github.event_name != 'pull_request' || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  USE_BSPM: "true"
+  _R_CHECK_FORCE_SUGGESTS_: "false"
+  R_GH: true
+  GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+  altdoc:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    container:
+      image: rocker/r2u:latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # The quarto-actions/setup doesn't work in containers so need to install manually
+      # https://github.com/quarto-dev/quarto-actions/issues/12
+      - name: Manually install Quarto
+        run: |
+          wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.3.450/quarto-1.3.450-linux-amd64.deb
+          apt install ./quarto-1.3.450-linux-amd64.deb
+
+      - name: Package Dependencies
+        run: R -q -e 'remotes::install_deps(".", dependencies=TRUE)'
+
+      - name: Build Package
+        run: R CMD build --no-build-vignettes --no-manual .
+
+      - name: Build site
+        run: |
+          utils::install.packages(".", repos = NULL, type = "source")
+          altdoc::render_docs(parallel = TRUE, freeze = 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

NAMESPACE

@@ -3,3 +3,4 @@
 export(preview_docs)
 export(render_docs)
 export(setup_docs)
+export(setup_workflow)

NEWS.md

@@ -1,80 +1,81 @@
-# News
-
-## altdoc (development version)
-
-Breaking changes:
-
-* Functions renamed:
-  - `use_docute()`, `use_docsify()` and `use_mkdocs()` are combined into `setup_docs()` 
-  - `update_docs()` -> `render_docs()`
-  - `preview()` -> `preview_docs()`
-* `setup_docs()` (previously `use_*()`) no longer updates and previews the website by default.
-* `custom_reference` argument is removed. See the `Post-processing` vignette for a description of the new proposed workflow.
-* `theme` argument is removed. Users can change themes by editing settings files in `altdoc/`
-* `mkdocs` documentation is no longer stored in `docs/docs/`
-
-New:
-
-* Support Quarto websites as a documentation format.
-* Support Quarto vignettes (.qmd) in the `vignettes/` folder.
-* `render_docs(parallel=TRUE)` uses `future` to parallelize the rendering of vignettes and man pages.
-* `render_docs(freeze = TRUE)` no longer renders vignettes or man pages when they have not changed and are already stored in `docs/`.
-* Settings files are now permanently stored in the `altdoc/` directory. These files can be edited manually to customize the website.
-* Major internal changes to the .Rd -> .md conversion system. We now use Quarto to convert man pages and execute examples, and the man pages are stored in separate markdown files instead of combined in a single large file.
-* `mkdocs` now behaves like the other documentation generators and stores its files in `docs/`. This means that `mkdocs` websites can be deployed to Github Pages.
-* Improved vignettes
-* Do not reformat markdown header levels automatically, but raise a warning when there is more than one level 1 header.
-* Fewer dependencies.
-* Fix parsing for issue/PR references like [org/repo#111].
-* Changelog and News sections can be present simultaneously.
-* Support for `NEWS.Rd`, either in the root folder or in `inst/`
-
-## altdoc 0.2.2
-
-* If necessary, two spaces are automatically added in nested lists in the `NEWS` 
-  (or `Changelog`) file. 
-
-* This is the last release before a large rework of this package.
-
-## altdoc 0.2.1
-
-* Fix test failures on CRAN due to the new version of `usethis` 
-  (see https://github.com/cynkra/fledge/issues/683).
-
-## altdoc 0.2.0 
-
-#### Breaking changes
-
-* Vignettes are no longer automatically added to the file that defines the structure
-  of the website. Developers must now manually update this structure and the order
-  of their articles. Note that the name of the file defining the structure of the 
-  website differs based on the selected site builder. This file lives at the root
-  of `/docs` (`use_docsify()` = `_sidebar.md`; `use_docute()` = `index.html`; 
-  `use_mkdocs()` = `mkdocs.yml`).
-
-
-#### Major changes
-
-* `update_docs()` now updates the package version as well as altdoc version in 
-  the footer.
-
-* The NEWS or Changelog file included in the docs now automatically links issues,
-  pull requests and users (only works for projects on Github).
-
-* Vignettes are now always rendered by `use_*()` or `update_docs()`. Therefore,
-  the argument `convert_vignettes` is removed. Previously, they were only rendered 
-  if their content changed. This was problematic because the code in a vignette 
-  can have different output while the vignette in itself doesn't change (#37, #38).
-
-* New argument `custom_reference` in `use_*()` and `update_docs()`. If it is a
-  path to a custom R file then it uses this file to build the "Reference" section
-  in the docs (#35).
-
-#### Minor changes
-
-* Fix some CRAN failures.
-
-
-## altdoc 0.1.0
-
-* First version.
+# News
+
+## altdoc (development version)
+
+Breaking changes:
+
+* Functions renamed:
+  - `use_docute()`, `use_docsify()` and `use_mkdocs()` are combined into `setup_docs()` 
+  - `update_docs()` -> `render_docs()`
+  - `preview()` -> `preview_docs()`
+* `setup_docs()` (previously `use_*()`) no longer updates and previews the website by default.
+* `custom_reference` argument is removed. See the `Post-processing` vignette for a description of the new proposed workflow.
+* `theme` argument is removed. Users can change themes by editing settings files in `altdoc/`
+* `mkdocs` documentation is no longer stored in `docs/docs/`
+
+New:
+
+* Support Quarto websites as a documentation format.
+* Support Quarto vignettes (.qmd) in the `vignettes/` folder.
+* `render_docs(parallel=TRUE)` uses `future` to parallelize the rendering of vignettes and man pages.
+* `render_docs(freeze = TRUE)` no longer renders vignettes or man pages when they have not changed and are already stored in `docs/`.
+* Settings files are now permanently stored in the `altdoc/` directory. These files can be edited manually to customize the website.
+* Major internal changes to the .Rd -> .md conversion system. We now use Quarto to convert man pages and execute examples, and the man pages are stored in separate markdown files instead of combined in a single large file.
+* `mkdocs` now behaves like the other documentation generators and stores its files in `docs/`. This means that `mkdocs` websites can be deployed to Github Pages.
+* Improved vignettes
+* Do not reformat markdown header levels automatically, but raise a warning when there is more than one level 1 header.
+* Fewer dependencies.
+* Fix parsing for issue/PR references like [org/repo#111].
+* Changelog and News sections can be present simultaneously.
+* Support for `NEWS.Rd`, either in the root folder or in `inst/`
+* Automatically create a Github Actions workflow with `setup_workflow()`.
+
+## altdoc 0.2.2
+
+* If necessary, two spaces are automatically added in nested lists in the `NEWS` 
+  (or `Changelog`) file. 
+
+* This is the last release before a large rework of this package.
+
+## altdoc 0.2.1
+
+* Fix test failures on CRAN due to the new version of `usethis` 
+  (see https://github.com/cynkra/fledge/issues/683).
+
+## altdoc 0.2.0 
+
+#### Breaking changes
+
+* Vignettes are no longer automatically added to the file that defines the structure
+  of the website. Developers must now manually update this structure and the order
+  of their articles. Note that the name of the file defining the structure of the 
+  website differs based on the selected site builder. This file lives at the root
+  of `/docs` (`use_docsify()` = `_sidebar.md`; `use_docute()` = `index.html`; 
+  `use_mkdocs()` = `mkdocs.yml`).
+
+
+#### Major changes
+
+* `update_docs()` now updates the package version as well as altdoc version in 
+  the footer.
+
+* The NEWS or Changelog file included in the docs now automatically links issues,
+  pull requests and users (only works for projects on Github).
+
+* Vignettes are now always rendered by `use_*()` or `update_docs()`. Therefore,
+  the argument `convert_vignettes` is removed. Previously, they were only rendered 
+  if their content changed. This was problematic because the code in a vignette 
+  can have different output while the vignette in itself doesn't change (#37, #38).
+
+* New argument `custom_reference` in `use_*()` and `update_docs()`. If it is a
+  path to a custom R file then it uses this file to build the "Reference" section
+  in the docs (#35).
+
+#### Minor changes
+
+* Fix some CRAN failures.
+
+
+## altdoc 0.1.0
+
+* First version.

R/create_workflow.R

@@ -0,0 +1,41 @@
+#' Create a Github Actions workflow
+#'
+#' This function creates a Github Actions workflow in
+#' ".github/workflows/altdoc.yaml". This workflow will automatically render the
+#' website using the setup specified in the folder "altdoc" and will push the
+#' output to the branch "gh-pages".
+#'
+#' @inheritParams render_docs
+#'
+#' @return No value returned. Creates the file ".github/workflows/altdoc.yaml"
+#' @export
+#'
+#' @examples
+#' if (interactive()) {
+#'   setup_workflow()
+#' }
+setup_workflow <- function(path = ".") {
+
+  if (!fs::dir_exists(".github/workflows")) {
+    fs::dir_create(".github/workflows")
+  }
+  path <- .convert_path(path)
+
+  src <- system.file("misc/altdoc.yaml", package = "altdoc")
+  tar <- fs::path_join(c(path, ".github/workflows/altdoc.yaml"))
+  fs::file_copy(src, tar)
+
+  # Deal with mkdocs installation in workflow
+  doctype <- .doc_type(path)
+  workflow <- .readlines(tar)
+  start <- grep("\\$ALTDOC_MKDOCS_START", workflow)
+  end <- grep("\\$ALTDOC_MKDOCS_END", workflow)
+  if (doctype == "mkdocs") {
+    workflow <- workflow[-c(start, end)]
+  } else {
+    workflow <- workflow[-(start:end)]
+  }
+  writeLines(workflow, tar)
+
+  cli::cli_alert_success("{.file .github/workflows/altdoc.yaml} created.")
+}

R/man.R

@@ -60,7 +60,7 @@
     }
 
     if (isTRUE(worked)) {
-      .write_freeze(input = origin_Rd, path = src_dir, freeze = freeze) 
+      .write_freeze(input = origin_Rd, path = src_dir, freeze = freeze)
     }
 
     return(worked)
@@ -71,7 +71,6 @@
     conversion_worked <- future.apply::future_sapply(
       man_source,
       render_one_man,
-      freeze = freeze,
       future.seed = NULL)
   } else {
     # can't use message_info with {}
@@ -102,4 +101,4 @@
     cli::cli_par()
     cli::cli_end(id = "list-fail")
   }
-}
+}

R/setup_workflow.R

@@ -0,0 +1,23 @@
+create_workflow <- function(path = ".") {
+
+  if (!fs::dir_exists(".github/workflows")) {
+    fs::dir_create(".github/workflows")
+  }
+  src <- system.file("misc/altdoc.yaml", package = "altdoc")
+  tar <- ".github/workflows/altdoc.yaml"
+  fs::file_copy(src, tar)
+
+  # Deal with mkdocs installation in workflow
+  doctype <- .doc_type(path)
+  workflow <- .readlines(tar)
+  start <- grep("\\$ALTDOC_MKDOCS_START", workflow)
+  end <- grep("\\$ALTDOC_MKDOCS_END", workflow)
+  if (doctype == "mkdocs") {
+    workflow <- workflow[-c(start, end)]
+  } else {
+    workflow <- workflow[-(start:end)]
+  }
+  writeLines(workflow, tar)
+
+  cli::cli_alert_success("{.file .github/workflows/altdoc.yaml} created.")
+}

docs/CITATION.md

@@ -1,6 +1,7 @@
 # Citation
 
 ```verbatim
+
 To cite package ‘altdoc’ in publications use:
 
   Bacher E (????). _altdoc: Package Documentation Websites with
@@ -11,9 +12,11 @@ To cite package ‘altdoc’ in publications use:
 A BibTeX entry for LaTeX users is
 
   @Manual{,
-    title = {altdoc: Package Documentation Websites with 'Quarto', 'Docsify',
-'Docute', or 'MkDocs'},
+    title = {altdoc: Package Documentation Websites with 'Quarto', 'Docsify', 'Docute', or 'MkDocs'},
     author = {Etienne Bacher},
     note = {https://altdoc.etiennebacher.com, https://github.com/etiennebacher/altdoc},
   }
+
+
+
 ```

docs/NEWS.md

@@ -28,6 +28,7 @@ New:
 * Fix parsing for issue/PR references like [org/repo#111].
 * Changelog and News sections can be present simultaneously.
 * Support for `NEWS.Rd`, either in the root folder or in `inst/`
+* Automatically create a Github Actions workflow with `setup_workflow()`.
 
 ## altdoc 0.2.2
 

docs/index.html

@@ -37,7 +37,7 @@
 				sidebar: [
 					{title: 'Home', link: '/'},
           {title: 'Articles', children: [{title: 'Customize', link: '/vignettes/customize.md'}, {title: 'Deploy', link: '/vignettes/deploy.md'}, {title: 'Get Started', link: '/vignettes/get-started.md'}]},
-          {title: 'Reference', children: [{title: 'preview_docs', link: '/man/preview_docs.md'}, {title: 'render_docs', link: '/man/render_docs.md'}, {title: 'setup_docs', link: '/man/setup_docs.md'}]},
+          {title: 'Reference', children: [{title: 'preview_docs', link: '/man/preview_docs.md'}, {title: 'render_docs', link: '/man/render_docs.md'}, {title: 'setup_docs', link: '/man/setup_docs.md'}, {title: 'setup_workflow', link: '/man/setup_workflow.md'}]},
 					{title: 'News', link: '/NEWS.md'},
 					{title: 'License', link: '/LICENSE.md'},
 					{title: 'Citation', link: '/CITATION.md'}

docs/man/preview_docs.md

@@ -15,9 +15,9 @@ Preview the documentation in a webpage or in viewer
 ## Arguments
 
 <table>
-<tr>
+<tr style="vertical-align: top;">
 <td style="white-space: nowrap; font-family: monospace; vertical-align: top">
-<code id="preview_docs_:_path">path</code>
+<code>path</code>
 </td>
 <td>
 Path to the package root directory.