Deploy docs to gh-pages on merge

ezmiller commented 9 months ago

Goal

This PR changes the deployment for Tablecloth's documentation. Currently, we use the Github pages feature to serve our documentation fro the doc folder on the master branch. This works fine, but we want to be able to preview documentation changes on PRs.

We can do that by using an action that deploys documentation previews into a "namespaced" folder within the docs folder on the branch that we serve from. In our case, using current configuration, it would deploy previews to the master branch within a directory like ./docs/preview/pr-100. This is not ideal because it leads to a bunch of meaningless commits on our master branch.

Instead, we can change our configuration to serve documentation from a branch called gh-pages. This is the default behavior that Github encourages. In this scenarios when we open a PR that includes changes to documentation, we will deploy those changes not to master -- leaving that commit history clean -- and instead commit to gh-pages.

Solution

To do this we need two actions: one that deploys the docs preview, and another on PR merge to master that deploys the official version of the documentation to gh-pages if there have been any changes to the docs. See the workflows added in the diff for this PR to see how that's done. High level summary:

When you merge a PR into master, changes to the docs folder will be deployed on the gh-pages branch at the root. That means that we can change the Github pages setting to use the gh-pages branch and load the index.html from the root.
Then, when you open a PR, if there have been changes to the files in the docs folder, then those will be deployed to the gh-pages branch under the directory ./docs/pr-preview/pr-<pr#>. Those preview docs will be loadable from the link https://sicloj.github.io/tablecloth/pr-preview/pr-<pr#>.

Test

We can't test this fully until we change the github pages setting. However, I made a trivial change to the docs to show that the deployment of the pr-review works. See here: https://github.com/scicloj/tablecloth/tree/gh-pages/pr-preview/pr-138.

github-actions[bot] commented 9 months ago

PR Preview Action v1.4.7 :---: Preview removed because the pull request was closed. 2024-03-09 20:19 UTC

ezmiller commented 8 months ago

@ezmiller, this looks great to me (but I am not so experienced with gh actions and might possibly overlook something).

(If I understand the action definitions correctly, changes to docs on the master branch will be deployed to gh-pages not only on PR merges, but on any push. That is good, I think.)

I think you've understood it correctly. If you were to push directly to origin/master (which one should probably avoid) that would in fact redeploy the docs if there were changes to files within the docs directory.

scicloj / tablecloth