Port website to Franklin.jl

darsnack commented 1 year ago

This closes #136. I have aimed for a 1-1 port of the site with minimal changes.

darsnack commented 1 year ago

I will tackle the previews and CI tomorrow.

darsnack commented 1 year ago

It seems previews require using Netlify? @Saransh-cpp do you have any experience here that avoids Netlify?

Saransh-cpp commented 1 year ago

Hmm, I think using GH pages instead of Netlify should be possible. The documentation states -

Now for the final step, you will need to visualize the obtained previews. Since Github only allow you to deploy one branch, you will need an alternative like Netlify. Create an account on Netlify.com, add your repository and chose the gh-preview branch without any additional settings. Set your Netlify website to be {netlify name}.netlify.app.

But, Documenter.jl already provides us with the "preview" feature using GH pages. This is due to the fact that Documenter.jl stores both the previews and the actual build in the same branch - gh-pages. For example see the gh-pages branch branch of Flux. The branch has a directory named previews to store the previews.

Ideally we should be able to do this using -

- name: Fix URLs for PR preview deployment (pull request previews)
  if: github.event_name == 'pull_request'
  run: |
    echo "PREVIEW_FRANKLIN_WEBSITE_URL=https://fluxml.ai/previews/PR${{ github.event.number }}/" >> $GITHUB_ENV
    echo "PREVIEW_FRANKLIN_PREPATH=previews/PR${{ github.event.number }}" >> $GITHUB_ENV
- name: Deploy (preview)
  if: github.event_name == 'pull_request' && github.repository == github.event.pull_request.head.repo.full_name # if this build is a PR build and the PR is NOT from a fork
  uses: JamesIves/github-pages-deploy-action@releases/v3
  with:
      BRANCH: gh-pages # The branch where the PRs previews are stored
      FOLDER: __site
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      TARGET_FOLDER: "previews/PR${{ github.event.number }}" # The website preview is going to be stored in a subfolder
  - name: Deploy (main)
  if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
  uses: JamesIves/github-pages-deploy-action@releases/v3
  with:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      BRANCH: gh-pages # Replace here the branch where your website is deployed
      FOLDER: __site

Could you point me to a repository already using Franklin? I can check their gh-pages branch for more insights. I'll create an issue in Franklin's repository about this.

Saransh-cpp commented 1 year ago

I got it working! I have created a PR in your fork to set everything up - https://github.com/darsnack/fluxml.github.io/pull/1. Merging this into the franklin branch should make everything work!

Here is the working demo -

The test repository - https://github.com/Saransh-cpp/fluxml-franklin-port/tree/main
The deployed website - https://saransh-cpp.github.io/fluxml-franklin-port/
A PR that tries to remove some contents from the website - https://github.com/Saransh-cpp/fluxml-franklin-port/pull/1
The bot's comment - https://github.com/Saransh-cpp/fluxml-franklin-port/pull/1#issuecomment-1272356666
The preview documentation - https://saransh-cpp.github.io/fluxml-franklin-port/previews/PR1

Time to update Franklin's documentation 😉

mcabbott commented 1 year ago

Just because I found the links for another thread...

Turing has a nice setup in which the docs are integrated (at least visually) into the website. Maybe we can steal things from how they do it at https://github.com/TuringLang/turinglang.github.io

Saransh-cpp commented 1 year ago

That does look nice, but the website looks a bit off in smaller screens. Maybe we should build up on the new website in new PRs and let this one go in as it is. That also brings up the question of how long will we be keeping the docs in Documenter (given how good the upcoming version of Pollen looks 👀 )

darsnack commented 1 year ago

The bot isn't commenting because the PR is from a fork instead of a branch. Not sure if we need to keep that restriction. Is it just a permissions thing for pushing deployments?

Either way, we won't be able to view the deployment until the repo is configured to deploy from gh-pages. Not sure if making that change will bring the current site down temporarily.

I would like to merge this sooner rather than later, since rebasing this PR is a bit annoying.

Saransh-cpp commented 1 year ago

The bot isn't commenting because the PR is from a fork instead of a branch. Not sure if we need to keep that restriction. Is it just a permissions thing for pushing deployments?

Similar to Documenter.jl, we cannot generate previews for a PR from a fork. I think GitHub Actions by default do not let us pass secret keys into forks (would compromise the repository); hence, if we turn this on, the PR build will simply fail.