Skip to content

Latest commit

 

History

History
106 lines (62 loc) · 3.3 KB

README.md

File metadata and controls

106 lines (62 loc) · 3.3 KB
Raw

MultiVersion pkgdown docs action

Github Action to generate multiple versions of pkgdown docs for R packages.

This Github Actions works under the following assumptions:

  • R package documentation is generated by the R function pkgdown::build_site
  • Documentation is published to the gh-pages branch of the package repository and Github Pages is enabled at the root level of the branch
  • The version of pkgdown used to generate the documentation is >= v2.0.0
  • The pkgdown documentation uses Bootstrap 5
  • The URL field in the package DESCRIPTION file contains a reference to the pkgdown site URL (see step 1 here)

An example of the output of the action can be seen below:

Screenshot with example output

Action type

Composite

Inputs

  • path:

    Description: Path to package's root

    Required: false

    Default: .

  • default-landing-page:

    Description: The default branch or tag on gh-pages that corresponds to the landing page. For instance, if your root index page on gh-pages is built using the 'main' branch, then the root page of the website will correspond to this page. If 'latest-tag' is selected, then the latest version will become the default.

    Required: false

    Default: main

  • branches-or-tags-to-list:

    Description: Which branches or tags should be listed under the 'Versions' dropdown menu on the landing page? This input should be a regular expression in R.

    Required: false

    Default: ^main$|^devel$|^pre-release$|^latest-tag$|^develop$|^v([0-9]+\\.)?([0-9]+\\.)?([0-9]+)$

  • insert-after-section:

    Description: After which section in the navbar should the 'Versions' dropdown be added? Choose between 'Reference' and 'Changelog' for the surest of choices.

    Required: false

    Default: Changelog

  • version-tab:

    Description: Configuration of how the drop-down list should appear for multiple versions. It should be set as an ASCII text representation of an R list object. Example:

      list(config = list(
    tooltip = list(
      main = "Tooltip for main branch"
    ),
    text = list(
      main = "main branch"
    )
  ))

    String should be quoted with " sign

    Required: false

    Default: ``

  • refs-order:

    Description: The order in which refs should appear in the drop-down list. Versions not in the vector will appear below refs listed here.

    If docs have never been generated for the ref, the ref will not appear in the drop-down. Similarly, if docs have been generated for the ref, but the ref is not listed in the vector, it will not appear in the drop-down.

    Example: c("main", "devel", "pre-release", "latest-tag")

    Required: false

    Default: c("main", "devel", "pre-release", "latest-tag")

  • latest-tag-alt-name:

    Description: An alternate name for the 'latest-tag' item

    Required: false

    Default: ''

Outputs

None.

Usage

Please refer to this example workflow to see how this action is used in an end-to-end documentation publishing workflow.