Fix gh-pages deployment cache "path" argument must be of type string undefined.

[gerteck]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• DevOps
• Improve developer experience
• Others, please explain:

Fixes #2547

Overview of changes:

Fixes CACHE_DIR issue in markbind deploy

In short, the cause of the CACHE_DIR bug is due to specific implementation used by dependency gh-pages involved in the markbind deploy workflow. To fix this, we manually set the cache dir in the deployment workflow.

Anything you'd like to highlight/discuss:

Bug Faced:

• When attempting to run markbind deploy without a package.json file, or without setting env var CACHE_DIR manually, user gets the "path" argument must of of type string error, and deployment fails.
• This has implications on CI platforms Travis, AppVeyor, Circle as well, as they make use of this deployment process.

Cause of Bug:
The bug is caused by the find-cache-dir dependency within the gh-pages module, used in the markbind deploy workflow.

• This dependency attempts to locate a cache directory by searching for a package.json file in the current or parent directories. If no package.json is found, it returns undefined, causing the deployment to fail.
• The absence of a package.json file in MarkBind projects leads to the undefined return value, breaking the workflow.
• This issue likely surfaced when the gh-pages version was bumped from v2.2.0 to v5.0.0 in MarkBind, where find-cache-dir was introduced in v3.1 of gh-pages.

Others:

• A previous PR Specify CACHE_DIR when deploying with GH actions #2542 laid groundwork for this bug fix (for GitHub actions).
• Refer to findings in Investigate gh-pages deployment cache "path not file" after updating to latest version #2547 for further elaboration if needed.

Fix:
To work around this, let's manually set the cache directory used by gh-pages to node_modules/.cache/gh-pages, by setting the CACHE_DIR environment variable in the deployment workflow. This follows the cache location detailed in gh-pages changelog.

Edit: Clarity.

Testing instructions:

1. clone branch
2. Resetting CACHE_DIR = " ". ($env:CACHE_DIR = "" on powershell / set CACHE_DIR=cache / echo %CACHE_DIR%)
3. Verify that markbind deploy works

Unfortunately, unable to test on CI platforms.

Proposed commit message: (wrap lines at 72 characters)

Fix CACHE_DIR issue in markbind deploy

Manually sets cache directory used by gh-pages to
node_modules/.cache/gh-pages. This is needed as sub-dependency
find-cache-dir dependency in gh-pages assumes presence
of package.json file and a node_modules directory to deterrmine
cache, which do not exist in a MarkBind project.

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

---

Reviewer checklist:

Indicate the SEMVER impact of the PR:

• Major (when you make incompatible API changes)
• Minor (when you add functionality in a backward compatible manner)
• Patch (when you make backward compatible bug fixes)

At the end of the review, please label the PR with the appropriate label: r.Major, r.Minor, r.Patch.

Breaking change release note preparation (if applicable):

• To be included in the release note for any feature that is made obsolete/breaking

Give a brief explanation note about:

• what was the old feature that was made obsolete
• any replacement feature (if any), and
• how the author should modify his website to migrate from the old feature to the replacement feature (if possible).

[damithc]

Thanks for attempting to fix this @gerteck
As per this fix, what will be the cache directory?
On a related note, I have been setting the cache directory manually (to get around this problem). I noticed that when I switch my CS2103 website repo to a different branch (e.g., to deploy to CS2113 website), the cache directory created when deploying to CS2103 website (which still remains) will interfere with the new deployment, and I have to delete the stale cache directory for the deploy to get working again. Sharing in case that is relevant to the fix.

[gerteck]

As per this fix, what will be the cache directory? On a related note, I have been setting the cache directory manually (to get around this problem). I noticed that when I switch my CS2103 website repo to a different branch (e.g., to deploy to CS2113 website), the cache directory created when deploying to CS2103 website (which still remains) will interfere with the new deployment, and I have to delete the stale cache directory for the deploy to get working again. Sharing in case that is relevant to the fix.

Oh! yes, I think that is a very good point that I did not consider. Currently, I had simply set the cache directory as .cache/gh-pages, if there is no current cache_dir set manually by the user. However, this wouldn't solve the issue of the stale cache.

• Perhaps it would be more appropriate to write temporary files to node_modules/.cache/gh-pages directory instead?
• Or I could also use the tempPath directory, i.e. .temp folder
• Perhaps we could add clean up into the deployment process as well?

Snippet from gh-pages:

The gh-pages module writes temporary files to a node_modules/.cache/gh-pages directory. The location of this directory can be customized by setting the CACHE_DIR environment variable.

If gh-pages fails, you may find that you need to manually clean up the cache directory. To remove the cache directory, run node_modules/gh-pages/bin/gh-pages-clean or remove node_modules/.cache/gh-pages.

It seems my PR can be greatly refined 😥

[gerteck]

• Set the cache directory to /node_modules/.cache. Generated files by gh-pages will subsequently be generated in /node_modules/.cache/gh-pages

• Added clean up that empties /node_modules/.cache/gh-pages directory before running gh-pages.

[Tim-Siu]

Thank youf for your research on the cache problem! From my testing I think the PR succesfully mitigated the cache path not specified problem and also addressed the cache not cleaned up concern.

[github-actions]

@Tim-Siu Each PR must have a SEMVER impact label, please remember to label the PR properly.