Merge pull request #4 from TuringLang/py/multiple-actions

Add DocsDocumenter action

DocsDocumenter/action.yml

@@ -0,0 +1,79 @@
+name: 'Build Documenter.jl site'
+author: 'TuringLang'
+description: 'Build and deploy Documenter.jl site, with a TuringLang navbar'
+
+inputs:
+  julia-version:
+    description: 'Julia version to use'
+    required: false
+    default: '1'
+  doc-path:
+    description: 'Path to the Documenter.jl source folder'
+    required: false
+    default: 'docs'
+  doc-make-path:
+    description: 'Path to the Documenter.jl build script'
+    required: false
+    default: 'docs/make.jl'
+  exclude-paths:
+    description: 'Comma-separated list of paths to exclude from navbar insertion.'
+    required: false
+    default: ''
+
+runs:
+  using: "composite"
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Setup Julia
+      uses: julia-actions/setup-julia@v2
+      with:
+        version: ${{ inputs.julia-version }}
+
+    - name: Cache Julia packages
+      uses: julia-actions/cache@v2
+
+    - name: Install docs dependencies
+      shell: julia --color=yes --project=${{ inputs.doc-path }} {0}
+      run: |
+        using Pkg
+        Pkg.develop(PackageSpec(path=pwd()))
+        Pkg.instantiate()
+
+    - name: Build docs
+      shell: bash
+      run: julia --project=${{ inputs.doc-path }} ${{ inputs.doc-make-path }}
+
+      # We want to use the same version of DocsNav. In principle we would like
+      # to write `uses: TuringLang/actions/DocsNav@${{ github.action_ref }}`,
+      # but the `uses` block doesn't allow for expressions. As a workaround,
+      # this step symlinks the actions directory to a fixed path so that we can
+      # use it later.
+      # See https://github.com/orgs/community/discussions/41927
+    - name: Symlink actions folder to a fixed path
+      env:
+        GH_ACTION_REPO: ${{ github.action_repository }}
+        GH_ACTION_REF: ${{ github.action_ref }}
+      shell: bash
+      run: ln -s /home/runner/work/_actions/$GH_ACTION_REPO/$GH_ACTION_REF/  /home/runner/work/_actions/current
+
+    - name: Insert navbar
+      # Using the path symlinked in the previous step
+      uses: ./../../_actions/current/DocsNav
+      with:
+        doc-path: ${{ inputs.doc-path }}
+        navbar-url: ${{ github.action_path }}/../DocsNav/scripts/TuringNavbar.html
+        exclude-paths: ${{ inputs.exclude-paths }}
+
+    - name: Deploy docs to gh-pages branch
+      working-directory: ${{ inputs.doc-path }}
+      shell: julia --color=yes --project=. {0}
+      # Must pass `root` when `deploydocs()` is run from outside make.jl file
+      # Also, `root` must be an absolute path (hence the call to `pwd()`)
+      run: |
+        using Documenter
+        deploydocs(; root=pwd(), repo="github.com/${{ github.repository }}.git", push_preview=true)
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+        JULIA_DEBUG: Documenter

README.md

@@ -1,16 +1,73 @@
-# DocsNav: Global Navigation for your Documentation
+# GitHub actions for TuringLang
+
+This repository contains a collection of GitHub actions to be used across different TuringLang repositories.
+
+## DocsNav
 
 This action inserts a MultiDocumenter-style top navigation bar to `Documenter.jl` generated sites.
 
-`TuringNavbar.html` in scripts directory contains code for building navigation bar for Turing language satellite packages' documentation but you can use your own navigation bar for your project!
+`TuringNavbar.html` in `DocsNav/scripts` directory contains code for building navigation bar for Turing language satellite packages' documentation but you can use your own navigation bar for your project!
 
-## How to use
+### Example usage
 
 ```yaml
 - name: Add Navbar
-  uses: TuringLang/DocsNav
+  uses: TuringLang/actions/DocsNav
   with:
     doc-path: 'Path to the Documenter.jl output', default: 'docs/build'
     navbar-url: 'URL of the navbar HTML to be inserted.', default: './scripts/TuringNavbar.html'
     exclude-paths: 'Comma-separated list of paths to exclude from navbar insertion.'
 ```
+
+### Parameters
+
+| Parameter | Description | Default |
+| --- | --- | --- |
+| `doc-path` | Path to the built HTML documentation | `docs/build` (following Documenter.jl conventions) |
+| `navbar-url` | Path to, or URL of, the navbar HTML to be inserted | `DocsNav/scripts/TuringNavbar.html` in this repository |
+| `exclude-paths` | Comma-separated list of paths to exclude from navbar insertion | `""` |
+
+----------
+
+## DocsDocumenter
+
+This action performs a complete build and deploy of Documenter.jl documentation, inserting the above navbar in the process.
+
+**Note**: This action takes care of calling `deploydocs()`, so your `docs/make.jl` file does not need to contain a call to `deploydocs()`.
+This does not affect local documentation building because `deploydocs()` doesn't do anything locally.However, on CI, it will cause the documentation to be deployed twice: once without the navbar and once with.
+
+### Example usage
+
+```yaml
+name: Build Documenter.jl docs
+
+on:
+  push:
+    branches:
+      - main
+    tags: '*'
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: read
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Build Documenter.jl docs
+        uses: TuringLang/DocsNav/DocsDocumenter
+```
+
+### Parameters
+
+| Parameter | Description | Default |
+| --- | --- | --- |
+| `doc-path` | Path to the documentation root | `docs` (following Documenter.jl conventions) |
+| `doc-make-path` | Path to the `make.jl` file | `docs/make.jl` (following Documenter.jl conventions) |
+| `julia-version` | Julia version to use | `'1'` |
+| `exclude-paths` | Comma-separated list of paths to exclude from navbar insertion | `""` |