You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The whole idea of the continuous integration of the tutorials is that whenever a user contributes a tutorial in the format of a .mlx file on the [tutorials repo](https://github.com/opencobra/COBRA.tutorials) it should be converted to html and then rendered accordingly on the Cobratoolbox website in the [tutorials section](https://opencobra.github.io/cobratoolbox/stable/tutorials/index.html). This involves using MATLAB on a self-hosted server (King server) to generate the html file. This html is then pushed to the websites codebase repository which is the [gh-pages branch](https://github.com/opencobra/cobratoolbox/tree/gh-pages) of the main cobratoolbox repository.
3
+
The whole idea of the continuous integration of the tutorials is that whenever a user contributes a tutorial in the format of a .mlx file on the [tutorials repo](https://github.com/opencobra/COBRA.tutorials) it should be converted to html and then rendered accordingly on the Cobratoolbox website in the tutorials section. This involves using MATLAB on a self-hosted server (King server) to generate the html file. This html is then pushed to the website's codebase repository which is the [./stable](https://github.com/opencobra/cobratoolbox/tree/gh-pages/stable) folder of the gh-pages branch of the main cobratoolbox repository.
4
4
5
-
GitHub actions is used to detect when a push (specifically .mlx push) is made to the tutorials repo. Then once the .mlx has been converted it is pushed to the gh-branch of the main repo. Again, GitHub actions can detect this push and configures the website to incorporate the extra tutorial.
5
+
GitHub actions is used to detect when a push (specifically .mlx push) is made to the tutorials repo. Then once the .mlx has been converted it is pushed to the stable folder of the gh-pages branch. Again, GitHub actions can detect this push and configures the website to incorporate the extra tutorial.
6
6
7
7
### Detailed Documentation
8
8
**Step 1: Pushing MLX files to the tutorials repository:**
9
-
To understand GitHub actions you need to look for the github workflow folder where you will find a .yml which contains all the details about the github action. The worflows can be found by navigating to ./.github/workflows/. In the tutorials repo you will find a ‘[main.yml](https://github.com/opencobra/COBRA.tutorials/blob/master/.github/workflows/main.yml)’ file.
9
+
To understand GitHub actions you need to look for the github workflow folder where you will find a .yml which contains all the details about the github action. The worflows can be found by navigating to ./.github/workflows/. In the tutorials repo you will find a ‘[main.yml](https://github.com/opencobra/COBRA.tutorials/blob/master/.github/workflows/main.yml)’ file.
10
10
11
11
**What does main.yml do?**
12
12
Here is an explanation of each section of the .yml file. Pictures of the sections are added and an explanation is given beneath the picture.
- The ‘runs-on’ parameter indicates where these jobs are computed. Here I specify it runs on ‘self-hosted’ because we need Matlab on King to run the .mlx to html. Generally, I would avoid using a self-hosted server but since Matlab is not an opensource programming language it needs to be ran a computer which has Matlab installed with a license.
40
+
- The ‘runs-on’ parameter indicates where these jobs are computed. Here, it runs on ‘self-hosted’ because we need Matlab on King to run the .mlx to html. Generally, we should avoid using a self-hosted server but since Matlab is not an opensource programming language it needs to be ran a computer which has Matlab installed with a license.
41
41
- There are several steps to do in the jobs section. Here the first step is to checkout the source repo i.e. get all the details about the repo and the pushes made to the repo.
echo "Copying the HTML, PDF, mlx and .m files to the target directory..."
79
+
cp "$HTML_FILE_PATH" "$TARGET_DIR/"
80
+
cd ../
81
+
fi
82
+
done
83
+
```
84
+
- Here we actually do the conversions and copy the .HTML file to cobratoolbox repository. The fourth line in this picture (changed_files=$(git diff --name-only HEAD~1 HEAD | grep '\.mlx' | tr '\n' ' ')) is used to find all the .mlx files that have been changed based on the most recent push.
85
+
- Then for each modified .mlx file, an HTML file, a pdf file, and a Matlab code file are created and stored in the same directory where the .mlx file is located. We are using MATLAB R2024a here, if the king server has some other version, then this step has to be modified accordingly. Further, HTML file alone is copied to the cobratoolbox repo.
67
86
68
-
The chmod command just makes the .sh files executable.
69
-
70
-
**Quick note on setup.sh and build.sh:**
71
-
72
-
• The setup.sh script automates the process of synchronizing .mlx files to the ghpages branch of the cobratoolbox GitHub repository. It requires three inputs: the repository identifier in owner/name format, a token for authentication, and the file path of the .mlx files to be synchronized. Upon execution, the script clones the cobratoolbox repository, configures git for automated operations, and targets aspecific directory within stable/tutorials/ to update. It clears this directory and copies the new .mlx files into it, ensuring that any changes are committed and pushed. This operation keeps the gh-pages branch of the cobratoolbox repository consistently updated with the latest .mlx files for documentation or tutorials.
73
-
74
-
• The build.sh script is designed for converting .mlx files to .html format and synchronizing them with the gh-pages branch of the cobratoolbox repository,. It takes three arguments: the repository identifier, a token for authentication, and the path of the .mlx file to be converted. Initially, the script converts the .mlx file to .html using MATLAB commands, assuming MATLAB is installed and accessible in the PATH. It then clones the target repository, sets up git with predefined user details, and switches to the gh-pages branch. The script creates a target directory within stable/tutorials/, copies the converted .html file into this directory, and finalizes by committing and pushing the changes.
75
-
76
-
• Both files can be found on the tutorial’s repository. Here are the links to [setup.sh](https://github.com/opencobra/COBRA.tutorials/blob/master/setup.sh) and [build.sh](https://github.com/opencobra/COBRA.tutorials/blob/master/build.sh)
77
87
78
88
```
79
-
- name: Sync with Destination Repo
80
-
run: |
81
-
counter=0
82
-
for file in ${{ steps.getfile.outputs.file }}; do
83
-
if [ $counter -eq 0 ]
84
-
then
85
-
# This is the first iteration, handle the file differently
git commit -m "Sync files from source repo" || echo "No changes to commit"
100
+
git push
101
+
cd ..
102
+
rm -rf cobratoolbox
103
+
git add .
104
+
git commit -m "created .HTML, .pdf and .m files"
105
+
git push origin master
106
+
echo "Script execution completed."
94
107
```
95
108
96
-
Here is the code to run the setup.sh and build.sh. We loop through all the .mlx files that were pushed. If it is the first file we are looking at we also run setup.sh to create the folder locations in the cobratoolbox – ghpages branch repository. Then afterwards build,sh is ran to convert the file to html and push to the created folder location
109
+
The converted files are further pushed to the cobratoolbox and COBRA.tutorial repo. Note that only .html pages are pushed to cobratoolbox repository and all the other formats are stored in COBRA.tutorial repo
97
110
98
111
### Configuring the King Server
99
112
@@ -102,6 +115,6 @@ Go to this page of the repo to create a new self-hosted runner:
By pressing the green new runner button, you are given easy instructions on how to set it up. You should have access to a terminal on King for this. To run the self-hosted runner nagivate to the folder you created it in and run ./run.sh to run the self-hosted runner.
118
+
By pressing the green new runner button, we are given easy instructions on how to set it up. We should have access to a terminal on King for this. To run the self-hosted runner nagivate to the folder we created it in and run ./run.sh to run the self-hosted runner.
106
119
107
-
You also need to make sure you have Matlab downloaded and working on the king server also. In the ‘[build.sh](https://github.com/opencobra/COBRA.tutorials/blob/master/build.sh)’ file the location of matlab is currently in my directory but you can add Matlab to another location and change the link to the location in the build.sh file.
120
+
We also need to make sure you have Matlab downloaded and working on the king server also.
0 commit comments