[DOC] Publish HTML documentation preview on surge (#128)

When documentation source files change, publish the generated
documentation to surge to easy the review.
Create a workflow that will later include a job to publish to
`gh-pages`.
The HTML documentation content is not customized nor updated. This will
be done later.

Author: tbouffard

.Rbuildignore

@@ -6,3 +6,6 @@
 ^.*\.md$
 ^doc$
 ^LICENSE$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$

.github/actions/build-setup/action.yml

@@ -0,0 +1,29 @@
+name: 'Build Setup'
+description: 'Setup R and install dependencies'
+inputs:
+  dependencies-extra-packages:
+    description: '`extra-packages` input for the `setup-r-dependencies` action.'
+    required: true
+  dependencies-needs:
+    description: '`needs` input for the `setup-r-dependencies` action.'
+    required: true
+  r-version:
+    description: 'The R version to use.'
+    required: true
+runs:
+  using: 'composite'
+  steps:
+    - uses: r-lib/actions/setup-r@v2
+      with:
+        r-version: ${{ inputs.r-version }}
+        use-public-rspm: true
+    - uses: r-lib/actions/setup-r-dependencies@v2
+      with:
+        extra-packages: ${{ inputs.dependencies-extra-packages }}
+        needs: ${{ inputs.dependencies-needs }}
+    # to generate documentation
+    - uses: r-lib/actions/setup-pandoc@v2
+    #  Sets up LaTeX with tinytex, for PDF generation
+    - uses: r-lib/actions/setup-tinytex@v2
+
+

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

@@ -8,6 +8,7 @@ on:
     tags:
       -  v*
     paths:
+      - '.github/actions/build-setup/**/*'
       - '.github/workflows/R-CMD-check.yaml'
       - 'R/**/*'
       - 'inst/**/*'
@@ -19,6 +20,7 @@ on:
     branches:
       - main
     paths:
+      - '.github/actions/build-setup/**/*'
       - '.github/workflows/R-CMD-check.yaml'
       - 'R/**/*'
       - 'inst/**/*'
@@ -49,14 +51,11 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
-      - uses: r-lib/actions/setup-r@v2
+      - uses: ./.github/actions/build-setup
         with:
+          dependencies-extra-packages: any::rcmdcheck
+          dependencies-needs: check
           r-version: ${{ matrix.config.r }}
-      - uses: r-lib/actions/setup-r-dependencies@v2
-        with:
-          extra-packages: any::rcmdcheck
-          needs: check
-      - uses: r-lib/actions/setup-pandoc@v2
       - uses: r-lib/actions/check-r-package@v2
 
 
@@ -74,12 +73,6 @@ jobs:
         with:
           name: ${{ matrix.config.os }}-r${{ matrix.config.r }}-source-package
           path: bpmnVisualization_*.tar.gz
-
-
-      #  Sets up LaTeX with tinytex, for PDF generation
-      # not needed before as the checks on the repo sources are done with --no-manual
-      - uses: r-lib/actions/setup-tinytex@v2
-
       - name: Check the source package
         id: source_package_checks
         run: R CMD check --as-cran bpmnVisualization_*.tar.gz

.github/workflows/publish-documentation.yml

@@ -0,0 +1,62 @@
+name: Publish Documentation
+
+on:
+  pull_request:
+    # To manage 'surge-preview' action teardown, add default event types + closed event type
+    types: [opened, synchronize, reopened, closed]
+    branches:
+      - main
+    paths:
+      - '.github/actions/build-setup/**/*'
+      - '.github/workflows/publish-documentation.yml'
+      - 'inst/**'
+      - 'man/**'
+      - '.Rbuildignore'
+      - '_pkgdown.yml'
+      - 'CONTRIBUTING.md'
+      - 'DESCRIPTION'
+      - 'README.md' # TODO use the right file, the repo from the repo cannot be included (wrong format, too much info)
+
+jobs:
+  # for Pull Request
+  pr_preview: # the id is used by surge to generate the surge url
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-22.04
+    permissions:
+      pull-requests: write # surge-preview: PR comments
+    steps:
+      - uses: actions/checkout@v3
+        if: github.event.action != 'closed'
+      - uses: ./.github/actions/build-setup
+        if: github.event.action != 'closed'
+        with:
+          dependencies-extra-packages: any::pkgdown, local::.
+          dependencies-needs: website
+          r-version: release
+      - name: Build documentation website
+        if: github.event.action != 'closed'
+        shell: Rscript {0}
+        run: |
+          pkgdown::build_site()
+      # Always upload the website for local browsing and when it cannot be deployed to surge
+      - name: Upload documentation
+        if: github.event.action != 'closed'
+        uses: actions/upload-artifact@v3
+        with:
+          name: documentation-${{github.sha}}
+          path: docs
+      - uses: bonitasoft/actions/packages/surge-preview-tools@v2
+        id: surge-preview-tools
+        with:
+          surge-token: ${{ secrets.SURGE_TOKEN }}
+      - name: Manage surge preview
+        if: steps.surge-preview-tools.outputs.can-run-surge-command == 'true'
+        id: doc_preview
+        uses: afc163/surge-preview@v1
+        with:
+          surge_token: ${{ secrets.SURGE_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          dist: docs
+          failOnError: true
+          teardown: true
+          build: ls -lh docs

.gitignore

@@ -44,3 +44,6 @@ vignettes/*.pdf
 
 # R Environment Variables
 .Renviron
+
+# Generated documentation
+docs

CONTRIBUTING.md

@@ -113,6 +113,22 @@ To regenerate this documentation after function comment updating, run this comma
 devtools::document()
 ```
 
+### Generate the HTML documentation (site)
+
+The HTML documentation is generated with [pkgdown](https://pkgdown.r-lib.org).
+
+If you need to test locally changes in the configuration or content of this documentation, install `pkgdown` following the [official documentation](https://pkgdown.r-lib.org/#installation).
+
+**Note**: on Ubuntu, you may encounter errors during the installation of `pkgdown`. In particular, the installation of some dependent packages may fail:
+- `systemfonts`: run `sudo apt -y install libfontconfig1-dev` (see [systemfonts#35](https://github.com/r-lib/systemfonts/issues/35#issuecomment-633560151) )
+- `textshapping`: `run sudo apt -y install libharfbuzz-dev libfribidi-dev` 
+
+Once `pkgdown` is installed, you can generate the HTML documentation quickly with this command:
+```
+pkgdown::build_site(devel = TRUE, lazy = TRUE, preview = FALSE)
+```
+For more details about the available options, see [the official documentation](https://pkgdown.r-lib.org/reference/build_site.html).
+
 ### bpmn-visualization TypeScript library update
 
 The [bpmn-visualization](https://github.com/process-analytics/bpmn-visualization-js) dependency is automatically updated by the [Update bpmn-visualization version](.github/workflows/update_bpmn_visualization_version.yml) workflow when a new version of this library is released.