Add build script for releases

[vijayiyer05]

Suggest to add a build script using the build tool which covers the following steps:

• Running the example live scripts so they all show their outputs
• Bumping the release number in Contents.m (useful for showcasing compute environment in DandiHub)

[vijayiyer05]

@ehennestad: one thing discussed in the overview by @bpancras at the recent "campfire chat" was the build tool.
This issue raised last year suggested some low-hanging fruit this system could help to achieve in the BOT context.
Maybe useful as a quick way to get familiar with it (if not already).

[ehennestad]

Yes, this should be straight-forward.

A couple of questions:
I know you can run export(..., Run=true) to run livescripts and they will show their outputs. Also, I have found the internal function matlab.internal.liveeditor.executeAndSave which is useful if you don't need to save. Do you know of any non-internal methods for doing this?

Also, maybe more important. I wanted to export a live script using a GitHub action, but got the following error:

 {�Error using matlab.internal.cef.webwindow
  DISPLAY environment variable must be set to a valid X11 display.
  
  Error in matlab.internal.liveeditor.LiveEditorUtilities.createDocument (line 26)
      webWindow = matlab.internal.cef.webwindow(url, matlab.internal.getDebugPort);
  
  Error in matlab.internal.liveeditor.LiveEditorUtilities.open>openUsingCEF (line 100)
                  LiveEditorUtilities.createDocument(timeout,webWindow);
  
  Error in matlab.internal.liveeditor.LiveEditorUtilities.open (line 33)
      [javaRichDocument, cleanupObj, webWindow] = openUsingCEF(fileName, reuse, timeout, webWindow);
  
  Error in export (line 116)
          matlab.internal.liveeditor.LiveEditorUtilities.open(...

The workflow runs on ubuntu-latest

Any ideas if that would be possible?

[vijayiyer05]

I'll see what I can learn re the issue. Can you share more about the use case for export here? Since the live script is rendered & runnable, I generally imagine export as nonessential for the class of lightweight projects (which I'd argue this currently still falls under).

[ehennestad]

Export of live scripts to html or markdown is nice for displaying the live script on a documentation page. For the bot, it could be nice to export to markdown and add to the github wiki. At the moment they are acessible on FEX but it seems that its not possible to link to them.

Having automatic re-export as part of a github actions workflow simplifies development, making sure the livescript in the documentation is always up to date

[vijayiyer05]

Thanks @ehennestad for elaborating. That's what I guessed the application would be!

Generally my opinion is: a build script seems heavyweight solely for the purpose of making live scripts viewable/linkable.

Wrt the File Exchange rendered versions, they are linkable in my hands, by using "Copy Link Address" from the browser. Can you see this on a second look?

That said, I recognize this is not elegant, and it's only sensible to update this link on the README at release versions, not at every commit. Given that there are other reasons for the build script (as listed above), I'm good with exporting to MD and/or HTML as an additional benefit: stable links for each of the rendered examples.

[ehennestad]

Generally my opinion is: a build script seems heavyweight solely for the purpose of making live scripts viewable/linkable.

Just out of curiosity, heavyweight in what sense?

Wrt the File Exchange rendered versions, they are linkable in my hands, by using "Copy Link Address" from the browser. Can you see this on a second look?

Yes I see it now:) Then I would suggest to update the links for the FileExchange badges in the readme tables to point directly to the tutorials and not the main FileExchange page for the BOT

[vijayiyer05]

Yes I see it now:) Then I would suggest to update the links for the FileExchange badges in the readme tables to point directly to the tutorials and not the main FileExchange page for the BOT

I encourage that update!

Just out of curiosity, heavyweight in what sense?

There's a class of user for whom GitHub is second nature but GitHub Actions is next level. I'm a bit queasy if rendering (which FX provides) is the reason they have to go through that transition. Imagine the experimental scientist (not a toolbox author) publishing the code for their figure publication on GitHub as part of an open science practice. I'd like to encourage them to use a live script to make it expository, without requiring them to learn/use GitHub Actions to make it broadly visible.

[mcafaro]

Regarding exporting live scripts in GitHub Actions: The export function requires the machine have a display but GitHub-hosted Linux runners do not provide a display by default.

You can set up a virtual display on GitHub-hosted Linux runners by using Xvfb display server to enable functions like export to work. Please see the example below:

name: Use Virtual Display on Linux Runner
on: [push]
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Start virtual display server
        if: runner.os == 'Linux'
        run: |
          sudo apt-get install -y xvfb
          Xvfb :99 &
          echo "DISPLAY=:99" >> $GITHUB_ENV

      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v2

      - name: Run MATLAB
         uses: matlab-actions/run-command@v2
         with:
           command: export("sample.mlx");

[ehennestad]

Thanks @mcafaro!

I have managed to get this far, but the next problem I have is the following error:
The MATLAB Editor is not available without Java.

I have tried to also add this to the workflow:

 - name: Set up Java 11
        uses: actions/setup-java@v3
        with:
          java-version: '11'
          distribution: 'temurin'  # Java distribution (e.g., 'adoptopenjdk', 'zulu')

It does not work, but I am not 100% on top of whether I am installing the right Java distribution, and I also suspect I might have to set some environment variables

[mcafaro]

@ehennestad Can you link me to the full workflow YAML and the job log with the error?

[ehennestad]

For the record, the solution posted above works, but I had not set the "DISPLAY" environment variable correctly. It is important that "DISPLAY" is set before the run-command step

[vijayiyer05]

Ty @ehennestad for the update and the insight into a subtle failure mode.

Please keep world posted (e.g., on this Issue) if you get a build script going. This would be a good story to share with the campfire cohort.