[External Software Permission Request] Jekyll Spaceship

ianyong commented 4 years ago

Library

Jekyll Spaceship

Purpose

For beautiful documentation. :')

License

Licensed under the MIT License.

damithc commented 4 years ago

Approved. Keep us posted if the plugin works out. We might want to adopt it for AB3. The plantUML support is especially interesting.

ianyong commented 4 years ago

Approved. Keep us posted if the plugin works out. We might want to adopt it for AB3. The plantUML support is especially interesting.

GitHub Pages runs in safe mode and only allows the following whitelisted dependencies. As such, I'm planning on adding a CI job to build the site without having to adhere to the safe mode restrictions, and then pushing the generated static files to a separate branch which will then be deployed.

I'm not sure whether I have to seek permission if I use pre-configured GitHub Actions, but this seems to do exactly what I want. If permission is required, I can open a new issue for it.

As for AB3 adoption, I think it wouldn't be too big a concern as long as the teaching team adds the necessary GitHub workflows to support whatever was described above in the base repo, since this proposed GitHub Pages deployment process is rather involved.

damithc commented 4 years ago

I'm not sure whether I have to seek permission if I use pre-configured GitHub Actions, but this seems to do exactly what I want. If permission is required, I can open a new issue for it.

Go ahead and use it @ianyong

As for AB3 adoption, I think it wouldn't be too big a concern as long as the teaching team adds the necessary GitHub workflows to support whatever was described above, since this proposed GitHub Pages deployment process is rather involved.

If we were to adopt it, it will be for future semesters, not this one. Let's see how it goes for your team. We can decide at the end of the semester.

GitHub Pages runs in safe mode and only allows the following whitelisted dependencies. As such, I'm planning on adding a CI job to build the site without having to adhere to the safe mode restrictions, and then pushing the generated static files to a separate branch which will then be deployed.

I think you'll need to push to the gh-pages branch as that's the branch used by GitHub pages.

ianyong commented 4 years ago

@damithc Hi Prof, just a quick update. We didn't end up using that GitHub Action as it only works with personal access tokens, and not the GITHUB_TOKEN secret that is automatically generated for every repository. It felt wrong to have to use personal access tokens for a team repo.

Also, it turns out that the github-pages gem handles a lot of things in the background, such as setting the name of the repo as the base URL. If anyone else is planning on doing this, do keep in mind that there will be a lot of troubleshooting involved. This was the GitHub workflow that we came up with: https://github.com/AY2021S1-CS2103T-W16-3/tp/blob/master/.github/workflows/build-jekyll.yml.

If we were to adopt it, it will be for future semesters, not this one. Let's see how it goes for your team. We can decide at the end of the semester.

As for whether it was worth all the trouble, we'll get back to you at the end of the semester. 😄

damithc commented 4 years ago

Thanks for the update @ianyong

ianyong commented 3 years ago

Keep us posted if the plugin works out. We might want to adopt it for AB3. The plantUML support is especially interesting.

We didn't end up using the PlantUML feature for the following reasons:

Inertia from inheriting the structure of AB3.
- Migrating the diagrams over to the Markdown files would have inflated someone's RepoSense contribution.
Having all the PlantUML source code embedded in the Markdown files might not be the best option for organisation.
- Makes the Markdown files much more lengthy and jarring to read (sudden PlantUML code in between paragraphs).
Might not support the existing styling of diagrams (i.e., !include style.puml).

The rest of the features are nice, but probably not worth the effort of setting up. At least we got cool looking tables and unrestricted emojis though.

damithc commented 3 years ago

Thanks for the update @ianyong Since we switch to Jekyll only recently, I suspect there are more some things we can do to take full advantage of Jekyll. Ideally, things that make the output look nicer, editing easier, without making things more complicated for students. Let us know if you find anything along those lines.

nus-cs2103-AY2021S1 / forum