generate_docs.pl should be able to run on Windows

[Jane Sandberg]

Right now, generate_docs.pl runs like a dream on Linux! But there are a few issues that prevent it from running on Windows:

1) The script provides some paths to binaries installed by npm. Windows doesn't quite recognize those node_modules/bin/* commands. A cleaner, cross-platform approach would be to just call `npx gulp` or `npx antora`, freeing us from having to deal with the paths inside the node_modules directory.
2) On line 110, the script calls the system cp command (while Windows uses copy instead of cp). It seems like we could just use Perl's File::Copy instead?
3) The antora command on line 121 sets a bunch of environment variables in the same line as the command. Windows doesn't support this same line environment variables. Also, windows and linux use different commands to set envvars (set vs export) Maybe we can do that with gulp?

Making this script Windows-friendly would allow more documentation folks to build the docs.

[Jane Sandberg (sandbergja)]

Here is a branch: https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/sandbergja/lp1930099_generate_docs_windows

It worked for me on both Windows and Mac OS.

To test on Windows:
1) Use the instructions provided in the comment at the top of generate_docs.pl.
2) Make sure that the locally generated documentation displays correctly in your browser.

To test for regressions on Linux or MacOs:
1) `cd /path/to/Evergreen/docs && perl generate_docs.pl`
2) Make sure that the locally generated documentation at /path/to/Evergreen/docs/output/index.html displays correctly in your browser.

[Blake GH (bmagic)]

Excellent! Works great! And I was pleased at how easy it was. Go Microsoft (I guess). The strawberry and the node folks deserve all of the cheer probably.

I made a small change to the instruction and signed off here:

https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/blake/lp1930099_generate_docs_windows

Since you already had the Release-note tag, I didn't add another one.

[Jane Sandberg (sandbergja)]

Thanks, Blake! I signed off on your commit, then found another mistake in my Windows instructions :-D. Apparently writing documentation about documentation is hard hahaha.

Signoff and additional commit available at: https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/sandbergja/lp1930099_generate_docs_windows

[Galen Charlton (gmc)]

I tested this using Git Bash (which includes a Perl of its own) and found:

- Strawberry Perl isn't needed if you're using Git Bash
- You do need Node from https://nodejs.org (but it's not necessary to invoke the option to install a C/C++ compiler and Python)
- Git Bash needs to be (re)started after Node is installed
- If generate_docs.pl fails with a message complaining "Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory", it may be necessary to do this before running generate_docs.pl:

export NODE_OPTIONS="--max-old-space-size=8192"

But with that, it generated the docs just fine as far as I can tell.

This comment is basically some testing notes for Andrea, who will give this a spin soon.

I've got no particular objection to installing Strawberry Perl, but it is useful to know that it isn't strictly necessary if one uses Git Bash.

[Jane Sandberg (sandbergja)]

Force-pushed today to take care of a merge conflict with bug 2036328

[Andrea Neiman (aneiman)]

100% possible that I am doing a weird git thing, but I am getting a conflict when I try to cherry-pick this to current main - both as a group of 3 commits as well as individually.

I will look at it again tomorrow and drag someone into shoulder-surfing with me.

[Galen Charlton (gmc)]

No, it legit needed a rebase, which is now available in working/collab/gmcharlt/lp1930099_gen_docs_win

[Galen Charlton (gmc)]

(And I've tested that rebase on both Linux and Windows and got sensible results, including verifying that we didn't regress on bug 2056480.)

[Andrea Neiman (aneiman)]

It might need another rebase before merging, which I attempted, but I got lost in the git-weeds -- regardless, it does the thing and build a nice docs preview to look at!

As a filthy Windows user I am delighted to have this available :) Thank you Jane, Galen, and Blake!

I have tested this code and consent to signing off with my name, Andrea Buntz Neiman, and my email, <email address hidden>.

[Galen Charlton (gmc)]

Pushed down to rel_3_11. Thanks, Jane, Blake, and Andrea!