Improve Documentation and Enable Continuous Previewing

[bassoy]

The improvement idea is to continuously create ascii-doctor documentation in order to

• validate the master documentation output
• preview the develop documentation output

[shikharvashistha]

I've been researching on the continuous integration for the asciidoctor documentation and concluded few things those are:

1. We can build whole project and check for html preview or validate the html using these:
   first && second

2. We can release a github page without using boost.build via:
   first

3. In place compile them without using the super project through this:
   first

4. html preview or validate the html file generated from 3rd step using these:
   first && second

• We can build whole project using boost build including all the html's (which we're not doing now "need to change the JAMFILE") and release a github page. I've created a sample here for reference.

[bassoy]

Comment is from @shikharvashistha:

I've been experimenting with the actions and successfully achieved :

I was able to compile asciidoc to html and create a auto release of github pages here && here.

Creating a html preview (only be generated when there is a change in compiled html file from asciidoc via actions in the commit) attaching example for reference this && this.

[bassoy]

@shikharvashistha
I like your last approach and I think you should follow the last approach using Github Actions.

[shikharvashistha]

@shikharvashistha I like your last approach and I think you should follow the last approach using Github Actions.

Yes I agree, to release a preview of documentation as discussed I'll be needing a dedicated branch which will look something like this. Is it feasible to use feature/doc for the implementation of my approach ?

[bassoy]

Yes please use feature/doc and let's see how it looks like.

[bassoy]

I propose to create a PR for the develop branch with the following changes:

• Integrate relevant contents of docs.yml into documentation.yml
• The specific action should be triggered for the develop branch
• The action should also contain a removal of the index.html on the remote before executing manoelcampos/asciidoctor-ghpages-action@v2

[shikharvashistha]

As there isn't a way to actually verify the correctness of documentation after some changes been done via commits in a pull request, so I would like to propose continuous previewing of documentation whenever any changes are being made to the same. Any suggestions are more than welcomed.

Wishes
@shikharvashistha