sitedoc.sh uses bash var. substring

[sdarwin]

This PR changes a line in sitedoc.sh to support macOS . Requires bash shell.

@alandefreitas , the web developers faced some confusion when following the README instructions. Consider this section:

./sitedoc.sh develop
./sitedoc.sh master
Site generation complete!
Open file:///home/user/path/to/antora/build/develop/doc in a browser to view your site.
Site generation complete!
Open file:///home/user/path/to/antora/build/doc in a browser to view your site.

Question 1: maybe it should it say this instead? (not sure, see next question also.)

./sitedoc.sh develop
# or
./sitedoc.sh master

They were running exactly what was written. Both commands:

./sitedoc.sh develop
./sitedoc.sh master

Question 2:

The contents of the S3 bucket has a master/ and a develop/ subdirectory. Notice in the example output there is coincidentally a path "build/develop". It makes it seem like there will be output in "build/master" and "build/develop", which matches what should be uploaded to S3. But in fact, that may be a coincidence, and really the sitedoc.sh output simply goes into "build". It may be not-obvious to write this sentence "path to antora build docs" in the format of a directory listing "/path/to/antora/build/develop/doc". It could more realistically say "/home/user/website-v2-docs/build". Will both master and develop builds go into the build directory, overwriting each other? Or, do master and develop builds have separate destination directories? what are they, by default? Are they overwriting each other, both in build/ ?

[cppalliance-bot]

An automated preview of the documentation is available at https://283.site-docs.prtest2.cppalliance.org/contributor-guide/index.html

[cppalliance-bot]

An automated preview of the documentation is available at https://283.site-docs.prtest2.cppalliance.org/contributor-guide/index.html

[cppalliance-bot]

An automated preview of the documentation is available at https://283.site-docs.prtest2.cppalliance.org/contributor-guide/index.html

[alandefreitas]

They were running exactly what was written.

Oh... that's bad. lol Yes. We need your # or comment.

Will both master and develop builds go into the build directory, overwriting each other

The answer to the second question is a bit longer. Vinnie came up with some conventions when we wrote this, and there is even a plugin that allows us to write macros to apply these conventions.

Anyway, one of the conventions is that "sitedocs" would be unversioned. Although Antora usually generates many versions of the same website for relevant branches and tags, sitedocs would be a single version (no subdirectory for develop, master, etc... - Antora allows this with a special version tag).

In other words, this is wrong:

website-v2-docs/site.playbook.yml

Lines 58 to 68 in 7b6fb65

	content:
	sources:
	- url: .
	start_path: user-guide
	edit_url: '{web_url}/edit/develop/{path}'
	- url: .
	start_path: formal-reviews
	edit_url: '{web_url}/edit/develop/{path}'
	- url: .
	start_path: contributor-guide
	edit_url: '{web_url}/edit/develop/{path}'

because it doesn't set which branches should be generated. By not setting the branches, they default to [HEAD, v{0..9}*], which is not what we want. We branches to be only HEAD locally and only master in production (HEAD is the same as master if the current work tree branch is master).

The usual solution for this in Antora, and what we have been doing before for other projects, like MrDocs and Boost.URL, would be to have two playbooks: a local-antora-playbook.yml and antora-playbook.yml. That's somewhat troublesome because we have to maintain two long files that are neatly equivalent. Any new contributor will get this wrong. The only difference is the branches options. I talked to the author of Antora, who knows that's bad and already opened an issue.

Fortunately, I solved this problem recently for MrDocs:

https://github.com/cppalliance/mrdocs/tree/develop/docs

We achieved the same thing there a single antora-playbook.yml in there and the scripts build_docs.sh and build_local_docs.sh look almost identical.

To do the same thing here, we add this extension I wrote to the playbook

https://github.com/cppalliance/mrdocs/blob/999ea4f3468ba3ad920b0cb91b56b5227c48d5a2/docs/antora-playbook.yml#L33-L35

where the branchesarray macro has the branches we want in production (master in the case of sitedocs). Then to build a local version of the playbook (something we don't properly support now), we just append --attribute branchesarray=HEAD when calling antora to use the contents of the current git worktree. Otherwise, it uses the contents of master which is what we want for the website.

[sdarwin]

@alandefreitas , your reply was detailed, and at the moment I am not following the thread. Which leads through mrdocs, antora, command-line options, and so on. That's ok. How about this:

Pull request 283 only fixes the macOS issue (which I believe it does.) Done.
In another PR, when you have a chance, you could update the README. Considering these points:

• "We need your # or comment."
• The README mentions multiple output dirs. Open file:///home/user/path/to/antora/build/develop/doc and Open file:///home/user/path/to/antora/build/doc. If switching to or it would only be one directory?
• A suggestion that the output location is described this way. (not required).

/home/user/website-v2-docs/build

or

/home/user/website-v2-docs/build (or wherever you have checked out the repository) 

• anything else

[alandefreitas]

Sure. I was answering the two questions you made but they are independent from the PR. The PR looks good to me.