updated doc and example action (#253)

* fixed example dep-action-version

* fixes for doc action

* added documenter to gh-ci-warning conversion

* fixed documenter http 301 in readme.md

* formatted

* renamed to jupyter-src; doc fixes

* doc fix

* reset inputs example to clear

* Update Example.yml

* Update Example.yml

* modified docs deploy target

* fixes for documantation

* Update Example.yml

* updated gitignores

* Update make.jl

* fixes for make.jl (for svg replacement)

* updates to match FMIFlux.jl structure

.github/workflows/Documentation.yml

@@ -35,13 +35,13 @@ jobs:
         env:
           WORK_TREE: './docs/src/examples'
           SRC_BRANCH: 'origin/examples'
-          SRC_FOLDER_PATH: 'examples/src'
+          SRC_FOLDER_PATH: 'examples'
         # copy the examples from the examples branch (.md, .svg) and copy the readme in the docs folder
         run: |
           git fetch
-          git --work-tree=$WORK_TREE/.. checkout $SRC_BRANCH -- $SRC_FOLDER_PATH/*.md $SRC_FOLDER_PATH/*.svg
-          mv $WORK_TREE/src/* $WORK_TREE 
-          rm -r $WORK_TREE/src
+          git --work-tree=$WORK_TREE/.. checkout $SRC_BRANCH -- $SRC_FOLDER_PATH/jupyter-src/*.md $SRC_FOLDER_PATH/jupyter-src/*.svg $SRC_FOLDER_PATH/pluto-src/*.html
+          mv $WORK_TREE/jupyter-src/* $WORK_TREE 
+          rm -r $WORK_TREE/jupyter-src
           cp ./README.md ./docs/src/index.md
 
       - name: "Install dependencies"

.github/workflows/Example.yml

@@ -39,25 +39,25 @@ jobs:
 
       - name: "Install packages"
         run: pip install jupyter nbconvert
-                        
-      - name: "Execute and synchronize all files"
+
+      - name: "Execute notebook"
         env:
-          FILE: examples/src/${{ matrix.file-name }}.ipynb
+          FILE: examples/jupyter-src/${{ matrix.file-name }}.ipynb
         run: |
           jupyter nbconvert --ExecutePreprocessor.kernel_name="julia-${{ matrix.julia-version }}" --to notebook --inplace --execute ${{ env.FILE }}
           jupyter nbconvert --to script ${{ env.FILE }}
           jupyter nbconvert --to markdown ${{ env.FILE }}
 
       - name: "run generated jl script to determine success of example building"
-        run: julia --project=examples/ examples/src/${{ matrix.file-name }}.jl
+        run: julia --project=examples/ examples/jupyter-src/${{ matrix.file-name }}.jl
 
       - name: "auto-commit (retry on merge)"
         if: success() && github.event_name != 'pull_request' && github.ref_name == 'main'
         uses: nick-fields/retry@v3
         env: 
-          CI_COMMIT_MESSAGE: example-${{ matrix.os }}-${{ matrix.file-name }}-${{ matrix.julia-version }}-${{ matrix.julia-arch }}-${{ matrix.experimental }}[${{ github.ref }}]
+          CI_COMMIT_MESSAGE: jupyter-example-${{ matrix.file-name }}-${{ matrix.os }}-${{ matrix.julia-version }}-${{ matrix.julia-arch }}-${{ matrix.experimental }}[${{ github.ref_name }}]
           CI_COMMIT_AUTHOR: github-actions[bot]
-          EXAMPLES_PATH: examples
+          EXAMPLES_PATH: examples/jupyter-src
         # Fetch all and clear the stash list. Include all files from the examples folder to the stash and switch the branch.
         # Reset the branch and remove all current files in the examples folder. 
         # Checkout the last stash to restore the new notebooks and apply the stash index to restore all other new files in the folder.
@@ -69,16 +69,19 @@ jobs:
           command: |
             git fetch --all
             git stash clear
-            git stash --include-untracked -- ${{ env.EXAMPLES_PATH }}
+            git stash --include-untracked -- ${{ env.EXAMPLES_PATH }}/${{ matrix.file-name }}*
             git switch examples
             git reset --hard origin/examples
+            rm -r ${{ env.EXAMPLES_PATH }}/${{ matrix.file-name }}*
             git checkout stash -f -- ${{ env.EXAMPLES_PATH }}
             git stash apply --index
             git stash drop
             git config --global user.name "${{ env.CI_COMMIT_AUTHOR }}"
             git config --global user.email "${{ env.CI_COMMIT_AUTHOR }}@users.noreply.github.com"
             git config --global core.autocrlf false
-            git add ${{ env.EXAMPLES_PATH }}
+            git pull
+            git reset
+            git add ${{ env.EXAMPLES_PATH }}/${{ matrix.file-name }}*
             git commit -m "${{ env.CI_COMMIT_MESSAGE }}"
             git push origin examples || (git reset --soft HEAD~1 && (exit 1))
 
@@ -89,20 +92,20 @@ jobs:
         uses: actions/checkout@v4
 
       - name: "Set up Julia"
-        uses: julia-actions/setup-julia@v1
+        uses: julia-actions/setup-julia@v2
         with:
             version: '1.10'
-
-      - run: julia -e 'using Pkg; Pkg.add("PlutoSliderServer"); Pkg.add("FMI")'
+            
+      - run: julia -e 'using Pkg; Pkg.add("PlutoSliderServer");'
       - run: julia -e 'using PlutoSliderServer; PlutoSliderServer.export_directory("examples/pluto-src")'
 
       - name: "auto-commit (retry on merge)"
         if: success() && github.event_name != 'pull_request' && github.ref_name == 'main'
         uses: nick-fields/retry@v3
         env: 
-          CI_COMMIT_MESSAGE: examples-pluto[${{ github.ref }}]
+          CI_COMMIT_MESSAGE: pluto-examples[${{ github.ref_name }}]
           CI_COMMIT_AUTHOR: github-actions[bot]
-          EXAMPLES_PATH: examples
+          EXAMPLES_PATH: examples/pluto-src
         # Fetch all and clear the stash list. Include all files from the examples folder to the stash and switch the branch.
         # Reset the branch and remove all current files in the examples folder. 
         # Checkout the last stash to restore the new notebooks and apply the stash index to restore all other new files in the folder.
@@ -117,17 +120,19 @@ jobs:
             git stash --include-untracked -- ${{ env.EXAMPLES_PATH }}
             git switch examples
             git reset --hard origin/examples
+            rm -r ${{ env.EXAMPLES_PATH }}/*
             git checkout stash -f -- ${{ env.EXAMPLES_PATH }}
             git stash apply --index
             git stash drop
             git config --global user.name "${{ env.CI_COMMIT_AUTHOR }}"
             git config --global user.email "${{ env.CI_COMMIT_AUTHOR }}@users.noreply.github.com"
             git config --global core.autocrlf false
             git pull
+            git reset
             git add ${{ env.EXAMPLES_PATH }}
             git commit -m "${{ env.CI_COMMIT_MESSAGE }}"
-            git push origin examples || (git reset --soft HEAD~1 && (exit 1))          
-  
+            git push origin examples || (git reset --soft HEAD~1 && (exit 1))
+            
   call-docu:
     needs: [jupyter, pluto]
     if: github.event_name != 'pull_request' && github.ref_name == 'main'

.github/workflows/Formatter.yml

@@ -3,6 +3,8 @@ on:
   pull_request:
     # this argument is not required if you don't use the `suggestion-label` input
     types: [ opened, reopened, synchronize, labeled, unlabeled ]
+  workflow_dispatch:
+
 jobs:
   code-style:
     runs-on: ubuntu-latest

.github/workflows/TestLTS.yml

@@ -54,4 +54,4 @@ jobs:
 
       # Run the tests
       - name: "Run tests"
-        uses: julia-actions/julia-runtest@v1
+        uses: julia-actions/julia-runtest@v1

.gitignore

@@ -24,7 +24,8 @@ docs/site/
 Manifest.toml
 LocalPreferences.toml
 
-# Custom
+# custom
 tmp/
-.vscode/settings.json
+build/
+.vscode/
 examples/jupyter-src/.ipynb_checkpoints/

docs/.gitignore

@@ -1 +1,2 @@
-build/
+build/
+Manifest.toml

docs/make.jl

@@ -10,18 +10,80 @@ using Documenter: GitHubActions
 using Suppressor
 
 example_pages = [
-    "Overview" => "examples/overview.md",
-    "Simulate" => "examples/simulate.md",
-    "Parameterize" => "examples/parameterize.md",
-    "Inputs" => "examples/inputs.md",
-    "Multiple instances" => "examples/multiple_instances.md",
-    "Modelica conference 2021" => "examples/modelica_conference_2021.md",
-    "Manipulation" => "examples/manipulation.md",
-    "Multithreading" => "examples/multithreading.md",
-    "Multiprocessing" => "examples/multiprocessing.md",
-    "Pluto Workshops" => "examples/workshops.md",
+    "Overview" => joinpath("examples", "overview.md"),
+    "Simulate" => joinpath("examples", "simulate.md"),
+    "Parameterize" => joinpath("examples", "parameterize.md"),
+    "Inputs" => joinpath("examples", "inputs.md"),
+    "Multiple instances" => joinpath("examples", "multiple_instances.md"),
+    "Modelica conference 2021" => joinpath("examples", "modelica_conference_2021.md"),
+    "Manipulation" => joinpath("examples", "manipulation.md"),
+    "Multithreading" => joinpath("examples", "multithreading.md"),
+    "Multiprocessing" => joinpath("examples", "multiprocessing.md"),
+    "Pluto Workshops" => joinpath("examples", "workshops.md"),
 ]
 
+#check if all md files in examples are included in docs
+for md in readdir(joinpath("docs", "src", "examples"))
+    if endswith(md, ".md") &&
+       !occursin("README", md) &&
+       all([!endswith(file, md) for (x, file) in example_pages])
+        print(
+            string(
+                "::warning title=Example-Warning::example \"",
+                md,
+                "\" is not included in the doc-manual\r\n",
+            ),
+        )
+    end
+end
+
+#remove any example pages, for witch the example can not be found
+# and remove svgs if md building failed
+for (x, md) in deepcopy(example_pages)
+    # check if file is missing
+    if !(any([occursin(file, md) for file in readdir(joinpath("docs", "src", "examples"))]))
+        print(
+            string(
+                "::warning title=Example-Warning::example-page \"",
+                md,
+                "\" is to be included in the doc-manual, but could not be found on the examples branch or in \"docs/src/examples\"\r\n",
+            ),
+        )
+        filter!(e -> e ≠ (x => md), example_pages)
+    else
+        # removal of svgs is here if there is xml data in the md
+        r = open(joinpath("docs", "src", md), "r")
+        s = read(r, String)
+        close(r)
+        if occursin("<svg", s) && occursin("</svg>", s)
+            print(
+                string(
+                    "::warning title=SVG-Warning::example-page \"",
+                    md,
+                    "\" has svg-xml text in it. Most likely, linking of support-files generated by jupyter is broken. The svg-xml text has been removed for the doc-manual, but also no plot will be displayed\r\n",
+                ),
+            )
+            # regex replace exeeds stack limit: s = replace(s, r"\<\?xml(?!<\/svg>)(.|\n)*?<\/svg>" => "")
+            # so take iterative approach:
+            while occursin("<?xml", s) && occursin("</svg>", s)
+                a = findfirst("<?xml", s)[1] - 1
+                b = findfirst("</svg>", s)[end] + 1
+                s = string(s[1:a], s[b:end])
+            end
+            w = open(joinpath("docs", "src", md * "tmp"), "w+")
+            write(w, s)
+            close(w)
+        end
+        if isfile(joinpath("docs", "src", md * "tmp"))
+            mv(
+                joinpath("docs", "src", md * "tmp"),
+                joinpath("docs", "src", md),
+                force = true,
+            )
+        end
+    end
+end
+
 my_makedocs() = makedocs(
     sitename = "FMI.jl",
     format = Documenter.HTML(
@@ -82,7 +144,7 @@ my_makedocs() = makedocs(
 function deployConfig()
     github_repository = get(ENV, "GITHUB_REPOSITORY", "")
     github_event_name = get(ENV, "GITHUB_EVENT_NAME", "")
-    if github_event_name == "workflow_run"
+    if github_event_name == "workflow_run" || github_event_name == "repository_dispatch"
         github_event_name = "push"
     end
     github_ref = get(ENV, "GITHUB_REF", "")
@@ -107,7 +169,7 @@ for w in warns
 end
 
 deploydocs(
-    repo = "github.com/ThummeTo/FMI.jl.git",
+    repo = string("github.com/", get(ENV, "GITHUB_REPOSITORY", ""), "git"),
     devbranch = "main",
     deploy_config = deployConfig(),
 )