Set up Community Showcase Handbook as a JupyterBook

[jmunroe]

Explorations from #17 suggest the following path:

• Create a new subdirectory in this repo called handbook that will contain the content of a JupyterBook for a 'Community Showcase Handbook'
• Populate handbook with a skeleton of a JupyterBook
• Revise the GitHub action .github/workflows/deploy_handbook.yml as needed to that the JupyterBook is built and pushed to GH Pages and so that this action is trigger if and only a change to the handbook/ subdirectory is made
  • Tidy up workflow to build and deploy Jupyter Book to GitHub Pages #26
• Set up GH Pages so that https://2i2c-org.github.io/community-showcase redirects to this new JupyterBook

[jmunroe]

We will want to document this process as a recommendation for other community who want to host their own JupyterBook.

area of confusion for James: Classic GitHub Pages?

or GH Pages with Actions?

[sgibson91]

So, the workflow I've always used previously is this:

• A GitHub Actions workflow file runs jupyterbook build . and commits the output build dir with html files to a gh-pages branch
• Configure "classic" GitHub Pages to "Deploy from a branch" (i.e. gh-pages)

I think the GitHub Actions option is a dressed up version of how they used to automate jekyll deployments which is old and janky.

[jmunroe]

Ok! "Classic" GitHub Pages it is!

@sgibson91 are you ok to fix/replace my first attempts to set up a JupyterBook within this repository as your first deliverable under sprint 3?

[sgibson91]

@jmunroe Yep!

[sgibson91]

Actually one follow-up question. Any particular reason for GitHub Pages over, say, readthedocs? GitHub Pages doesn't support deploy previews, so you can't visually check changes to the site before deploying them. Of course you can always build the docs in a PR and make sure they pass, but that's not the same as them being visually coherent.

[jmunroe]

The visual preview I am expecting is to build the JupyterBook within a JupyterLab instance, verify it looks the way it is intended, then check in the changes and have reasonable confidence that the GitHub pages deployment will look the same.

With RTD it's not clear to me how to render a RTD site without having first to make a commit and have RTD hooks build the site.

My intent is to have an authoring environment for JupyterBook that does not depend on tooling outside of what we can put inside of an environment image container.

[sgibson91]

That's totally fair. I was more curious than worried we were making a technical blunder.

[sgibson91]

Expect a few debug PRs now as I double check the workflow actually runs correctly 😄

[sgibson91]

Ok, the site is now live at https://2i2c.org/community-showcase/

[jmunroe]

I am seeing different GitHub actions and its not clear to me which action is doing what.

There is the Build and Deploy Handbook workflow (as described in deploy_handbook.yml`. I thought was following the recommended deployment guide as recommended by the JupyterBook project ( see https://jupyterbook.org/en/stable/publish/gh-pages.html )

But then there is also this pages-build-deployment workflow that although I see the action has been running, it doesn't appear defined in .github/workflows. Where is that workflow defined?

Are one of these way the 'old way' and the other the 'new way'? Or are they both used?

Also, I was expecting the JupyterBook to only be available through https://2i2c-org.github.io/community-showcase (which does work) but it seems "somehow" this is redirects to https://2i2c.org/community-showcase . There is nothing in the GH Pages configuration about setting 'custom domain' so I am not clear on why this is working.

[sgibson91]

I am seeing different GitHub actions and its not clear to me which action is doing what.

There is the Build and Deploy Handbook workflow (as described in deploy_handbook.yml`. I thought was following the recommended deployment guide as recommended by the JupyterBook project ( see jupyterbook.org/en/stable/publish/gh-pages.html )

But then there is also this pages-build-deployment workflow that although I see the action has been running, it doesn't appear defined in .github/workflows. Where is that workflow defined?

Are one of these way the 'old way' and the other the 'new way'? Or are they both used?

So all deploy_handbook.yml does is generate a bunch of HTML files and commit them to a branch on this repo. That in itself does not a website make. What GitHub Pages does (and indeed any static site hosting provider) is read those HTML files and put them on a server somewhere connected to the internet, handles a domain name, TLS certificates for HTTPS, and so on. None of which happens in our workflow, but it is part of the "magic" that makes GitHub Pages work. This all used to happen in the background in a black box until, in 2021, GitHub starting making the logs from this part of the process available to people via the GitHub Actions interface (and also the deployments page) to help folk understand gnarly edge cases when their workflow to build their website worked, but it's still not being deployed properly for some reason. See blog post. So there isn't a workflow file in our repo linked to those logs, because that part is kinda not our workflow - it's GitHub's. And I think this would still show up regardless of which choice we made in the Pages settings (and ultimately has nothing to do with whether we are deploying a Jupyter Book, a Jekyll site, a hugo site, a sphinx site, etc).

Also, I was expecting the JupyterBook to only be available through 2i2c-org.github.io/community-showcase (which does work) but it seems "somehow" this is redirects to 2i2c.org/community-showcase . There is nothing in the GH Pages configuration about setting 'custom domain' so I am not clear on why this is working.

I was also expecting this and was also a little surprised, but I think I understand now.

The https://github.com/2i2c-org/2i2c-org.github.io repo builds our https://2i2c.org site using GitHub Pages, and in it's settings you can see that the custom domain field has been filled such that it is served at 2i2c.org instead of 2i2c-org.github.io.

• The <name>.github.io repo (whether personal or at an org-level) is a special repo that is served at the <name>.github.io domain and acts as a "parent"
• Any other repo deploying GitHub Pages sites under the same namespace would automatically be served at <name>.github.io/<repo> as "children" of the parent domain
• It logically follows then (even if it is not explicitly explained!) that if you set a custom domain for the parent repo (which we have) then all the children automatically inherit it

Hope this helps!

[jmunroe]

Thank you! That makes it much more clear that pages-build-deployment was always occurring in the background but is now being exposed as a visible step!

And I appreciate understanding what is going on with the domain redirection. That makes a lot of sense that it is the https://github.com/2i2c-org/2i2c-org.github.io repo where the custom domain is being specified.

[jmunroe]

This completes what was envisioned for this issue! Closing.