Replacing bash script with Julia script for inserting navbar

[shravanngoswamii]

Closes #9 #10

[penelopeysm]

This is great - very lightweight code and well structured!

I have a few comments just to polish the edges really.

[shravanngoswamii]

@penelopeysm Thanks, I have updated the script with your suggested changes, let me know if we should add anything else!

One more thing, can we just schedule only DocsNav part of DocsDocumenter workflow on weekly basis so if our navbar script or navbar itself changes then we won't have to manually trigger workflows in all repos + we should also add worklow dispatch event in all repos so we can also trigger it manually if required...!

Most of our repos still use DocsNav.yml workflow from TuringLang/turinglang.github.io, I guess we are ready to use this everywhere...

[penelopeysm]

can we just schedule only DocsNav part of DocsDocumenter workflow

Hmmm, that's an interesting one. I do see the utility there.
I guess the strategy would be to clone the gh-pages branch and then edit every HTML file inside it?

[penelopeysm]

super happy with everything else :)

[shravanngoswamii]

I don't think we can schedule composite actions, let's just add a schedule in all workflow to run docs:

  schedule:
    - cron: '0 0 * * 0'  # Runs every week on Sunday at midnight (UTC)

[shravanngoswamii]

Let's merge this first so we can fix all broken docs!

[penelopeysm]

I'm thinking about how Documenter.jl attempts to be very smart about what docs it deploys. This isn't to do with our workflows, it's baked into Documenter.jl itself. For example

https://turinglang.org/DynamicPPL.jl/stable/ - this subdir is only updated when Documenter is run on a new tag

https://turinglang.org/DynamicPPL.jl/dev/ - this subdir is updated when Documenter is run on the main branch

https://turinglang.org/DynamicPPL.jl/v0.34/ - this subdir is updated when Documenter is run on 0.34

But if we update the navbar, we presumably want to edit all the subdirs at once. I think the only way to do that is something like this

name: Update navbar

on:
  schedule:
    - cron: '0 0 * * 0'
  workflow_dispatch:

jobs:
  update-navbar:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          ref: gh-pages

      [... install julia...]

      - name: Replace navbar
        uses: TuringLang/actions/DocsNav@v(whatever)
        with:
          doc-path: '.'

What do you think?

(Also, yes, it's definitely time to update all the workflows in the organisation repos. That'll be great fun 😅 )

[shravanngoswamii]

Should I tag it with v3? As it's a major change, Bash to Julia!

[penelopeysm]

I think we can be liberal with version numbers so yes :)

[shravanngoswamii]

What do you think?

How about something like this:

name: "Documentation"

on:
  push:
    branches:
      - main
    tags: '*'
  pull_request:
    branches:
      - main
  schedule:
    - cron: '0 0 * * 0'
  workflow_dispatch:

permissions:
  contents: write

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}

jobs:
  docs:
    runs-on: ubuntu-latest
    if: github.event_name != 'schedule'

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build and deploy Documenter.jl docs
        uses: TuringLang/actions/DocsDocumenter@(whatever)

  update-navbar:
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule'

    steps:
      - name: Checkout gh-pages branch
        uses: actions/checkout@v4
        with:
          ref: gh-pages

      - name: Insert navbar
        uses: TuringLang/actions/DocsNav@(whatever)
        with:
          julia: true (conditional installation😅)
          doc-path: '.'
          navbar-url: ${{ github.action_path }}/DocsNav/scripts/TuringNavbar.html

      - name: Commit and push changes
        run: |
          if [[ -n $(git status -s) ]]; then
            git add .
            git commit -m "Update navbar (automated)"
            git push "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" gh-pages
          else
            echo "No changes to commit"
          fi

[penelopeysm]

I think I have a slight preference for having two separate workflows, but yeah, that general structure should work!
I think its fine for DocsNav to require someone to do julia-actions/install-julia before it, many github actions don't auto install system dependencies :)

[penelopeysm]

Where would you like to go from here? Should we maybe update the workflows on DynamicPPL to start? Then once we're happy with it + confident that it works we can copy paste to the other repos?

[shravanngoswamii]

Where would you like to go from here?

I am fine with both approaches, but having only one workflow will require less future efforts in case of any change.

Should we maybe update the workflows on DynamicPPL to start? Then once we're happy with it + confident that it works we can copy paste to the other repos?

DynamicPPLs docs are broken so let's start with it, I guess you have owner access for DynamicPPL so can you test it out there, then I will start opening PRs for all other repos!