Island rhythms/cleanup

[vkarpov15]

Summary

The docs:prepare:publish:XYZ scripts are becoming hard to maintain and test. This cleans things up a bit so at least the logic from docs:clean:stable and mv ./docs/7.x ./tmp are moved to the website.js script. So the actions that don't change the branch are in one script.

Examples

[hasezoey]

i think this could be cleaned-up even more by relying on the versionObj like the generation of the website

also if all the logic is now in website.js for docs:clean:stable, shouldnt the script also be changed to use that instead (so we dont have duplicate actions)

if you want you can merge it as-is and i will try to update it with versionObj later

[vkarpov15]

@hasezoey I addressed your comments, can you please re-review?

[hasezoey]

those would likely need to be prefixed with versionObj.versionedPath (guessing by this workflow and how this function is always called)

[vkarpov15]

I don't think these paths need to be prefixed with versionedPath. This deleteAllHtmlFiles() function is meant to replace npm run docs:clean:stable; which cleans out index.html, docs/*.html, etc. regardless of whether this is a versioned deploy or not.

In other words, the workflow for a versioned deploy is 1) clear all docs, 2) generate docs, 3) copy docs to /tmp, 4) clear versionedPath, 5) copy /tmp to versionedPath. deleteAllHtmlFiles() takes care of step 1, not step 4.

[hasezoey]

I don't think these paths need to be prefixed with versionedPath. This deleteAllHtmlFiles() function is meant to replace npm run docs:clean:stable; which cleans out index.html, docs/*.html, etc. regardless of whether this is a versioned deploy or not.

is because of the git conflict if those files exist and you want to change to gh-pages?

if this is the case, could you add some kind of comment / JSDOC for future reference (on why it does not make use of versionedPath)

but because this is now a function of website.js, shouldnt it also at least try to clean the versionedPath to have a consistent new generation?

In other words, the workflow for a versioned deploy is 1) clear all docs, 2) generate docs, 3) copy docs to /tmp, 4) clear versionedPath, 5) copy /tmp to versionedPath. deleteAllHtmlFiles() takes care of step 1, not step 4.

just to be on a consistent page, this is the current workflow (to my understanding)

1. if latest, checkout gh-pages
2. if latest, merge master
3. if latest, clean /docs directoy
4. website.js is called
5. website.js will clean out the already generated files (if they exist) for the latest / unversioned deploy (to reduce the git conflicts?)
6. website.js will generate all files directly to versionedPath (pugify)
7. website.js will copy all static files directly to versionedPath, if not empty (because it does not need to copy in-place)
8. website.js if environment variable DOCS_DEPLOY is set, files in versionedPath will be moved to tmp (which is currently a bug, see my suggestion for when the function is called)
9. if versioned, the branch gh-pages is checked-out
10. if versioned, will delete the old /docs/X.X folder
11. if versioned, will copy folder tmp to the X.X
12. if latest, generate search

[vkarpov15]

is because of the git conflict if those files exist and you want to change to gh-pages? No, more to guard against silently out of date files and get rid of any files that we don't want to generate any more.

just to be on a consistent page, this is the current workflow (to my understanding) Not entirely correct. 7.x and 6.x workflows don't check out gh-pages, so no steps 1/2. But otherwise correct.

Re: Step 6, you're right, because website.js will generate all files directly to versionedPath, we do need to make deleteAllHtmlFiles() relative to versionedPath.

[hasezoey]

just to be on a consistent page, this is the current workflow (to my understanding) Not entirely correct. 7.x and 6.x workflows don't check out gh-pages, so no steps 1/2. But otherwise correct.

as it said if latest - which applies to the master branch (currently 8.x) and if versioned it means the X.x branches (like 7.x and 6.x) - versioned uses gh-pages checkout at step 9

[hasezoey]

I don't think these paths need to be prefixed with versionedPath. This deleteAllHtmlFiles() function is meant to replace npm run docs:clean:stable; which cleans out index.html, docs/*.html, etc. regardless of whether this is a versioned deploy or not.

is because of the git conflict if those files exist and you want to change to gh-pages?

if this is the case, could you add some kind of comment / JSDOC for future reference (on why it does not make use of versionedPath)

but because this is now a function of website.js, shouldnt it also at least try to clean the versionedPath to have a consistent new generation?

In other words, the workflow for a versioned deploy is 1) clear all docs, 2) generate docs, 3) copy docs to /tmp, 4) clear versionedPath, 5) copy /tmp to versionedPath. deleteAllHtmlFiles() takes care of step 1, not step 4.

just to be on a consistent page, this is the current workflow (to my understanding)

1. if latest, checkout gh-pages
2. if latest, merge master
3. if latest, clean /docs directoy
4. website.js is called
5. website.js will clean out the already generated files (if they exist) for the latest / unversioned deploy (to reduce the git conflicts?)
6. website.js will generate all files directly to versionedPath (pugify)
7. website.js will copy all static files directly to versionedPath, if not empty (because it does not need to copy in-place)
8. website.js if environment variable DOCS_DEPLOY is set, files in versionedPath will be moved to tmp (which is currently a bug, see my suggestion for when the function is called)
9. if versioned, the branch gh-pages is checked-out
10. if versioned, will delete the old /docs/X.X folder
11. if versioned, will copy folder tmp to the X.X
12. if latest, generate search

[hasezoey]

as a suggestion, you should probably not use '.' and use variable cwd instead