Deploy PR previews to branch folders

[nrichers]

Internal Notes for Reviewers

This PR adds the ability to deploy PR previews based on the working branch you are on. You can use this to deploy PR previews until we can automate the process via a GitHub workflow.

PR previews all go into a s3://docs-ci-cd-demo/site/pr_previews/$(GIT_BRANCH)/ folder to distinguish them from the rest of the docs-demo site which is otherwise largely untouched (see "One caveat").

Run make to see the new options:

Deploy a PR preview

Run make deploy-demo-branch:

The command line output gives you a link you can click to open the preview:

Delete

Run make delete-demo-branch:

This gives you the standard 404 and links then take you to the docs-demo site that is otherwise untouched.

Other ways of testing

You can also check that files get added or removed with the aws s3 command. E.g. check what happens with aws s3 ls s3://docs-ci-cd-demo/site/pr_previews/ before and after you run the new make commands.

One caveat

I had to remove the --delete option from the make deploy-demo command as it otherwise deletes the pr_previews/ subfolder. I think this an acceptable compromise as we might remove the regular docs-demo functionality at some point in the future. You mainly just need an index.html file in the root of the S3 bucket which we could generate in the future with all of the PR preview links.

External Release Notes

[validbeck]

Neato!!! Just one quick suggestion for the wording for delete-demo-branch as I had a hard time parsing the original notation.

Demo made:

Demo deleyeeted:

[github-actions]

PR Summary

This pull request introduces several enhancements to the Makefile used for managing the documentation site. The key changes include:

1. Branch-Specific Deployment and Cleanup:

   • Added a new variable GIT_BRANCH to capture the current git branch name.
   • Introduced two new targets: deploy-demo-branch and delete-demo-branch.
     • deploy-demo-branch: Deploys the documentation site for the current branch to a specific S3 path and invalidates the CloudFront cache.
     • delete-demo-branch: Deletes the documentation site for the current branch from the S3 path and invalidates the CloudFront cache.

2. Enhanced Help Section:

   • Updated the help section to include the new targets and improved formatting for better readability.

3. Refined Existing Targets:

   • Modified the deploy-demo target to remove the --delete flag from the aws s3 sync command, ensuring that files are not deleted during the sync process.

These changes aim to improve the deployment workflow by allowing branch-specific previews and cleanups, making it easier to manage documentation updates for different branches.

Test Suggestions

• Test the deploy-demo-branch target to ensure it correctly deploys the documentation site for the current branch to the specified S3 path.
• Test the delete-demo-branch target to ensure it correctly deletes the documentation site for the current branch from the specified S3 path.
• Verify that the deploy-demo target still functions correctly without the --delete flag.
• Run the help target to ensure the help message displays all available targets with the correct formatting.
• Test the clean, clone, notebooks, python-docs, get-source, docs-site, deploy-prod, and release-notes targets to ensure they are unaffected by the changes.

[nrichers]

Tweaked the help wording a bit since the suggested change is invalid syntax and was lacking some wording symmetry to show the relationship between the options: