Switch docs deployment from Travis CI to GitHub Actions

[gopi487krishna]

Migration of Documentation Deployment From Travis CI to GitHub Actions

This pull request is in reference to the issue #549 .

Changes Made

• A new workflow has been added named docs.yaml under the .github/workflow directory
• Three new actions have been introduced
• docs-prerequisites : Gets all the necessary packages for generating the documentation
• setup-boost : Sets up boost
• generate-publish-doc : Generates the documentation and uploads the necessary files ( as per the branch ) to gh-pages branch

References

#549

Tasklist

• Add test case(s)
• Ensure all CI builds pass
• Review and approve

[gopi487krishna]

@mloskot @lpranam Sir kindly review the PR

[gopi487krishna]

In travis configuration one thing I noticed is that the secure token was left exposed

I don't know what is the reason for that but I think it would be better if GitHub secrets are used instead.

Also currently as the secret is not created so the GitHub token field will be blank

[mloskot]

@gopi487krishna

In travis configuration one thing I noticed is that the secure token was left exposed

It is not exposed. It is encrypted.
https://docs.travis-ci.com/user/environment-variables/#defining-encrypted-variables-in-travisyml

[gopi487krishna]

@gopi487krishna

In travis configuration one thing I noticed is that the secure token was left exposed

It is not exposed. It is encrypted.
https://docs.travis-ci.com/user/environment-variables/#defining-encrypted-variables-in-travisyml

@mloskot I am sorry for not looking at the docs prior to asking. Thanks for the help sir.

[mloskot]

What's the status of this?

[gopi487krishna]

@mloskot Its already completed. Only the GIL_Token secret needs to be implemented at your end

[mloskot]

@gopi487krishna I don;'t have much experience with the GitHub Actions yet, I wonder, does it have to be named GIL_TEST_TOKEN? Here, for example, in https://docs.github.com/en/actions/reference/authentication-in-a-workflow#using-the-github_token-in-a-workflow it says secrets.GITHUB_TOKEN.

[gopi487krishna]

@mloskot No sir, It can be named anything as per your wish. Here are the steps just in case any confusion exists

[gopi487krishna]

@mloskot The secret name should be the name here ( which you named earlier)

[mloskot]

@gopi487krishna Thanks for the very detailed guide.

I've realised, interestingly, that I can not use GITHUB_TOKEN as a secret name:

Apparently, it is a reserved name because, as per https://docs.github.com/en/actions/reference/authentication-in-a-workflow

GitHub automatically creates a GITHUB_TOKEN secret to use in your workflow.
You can use the GITHUB_TOKEN to authenticate in a workflow run.

So, I'm trying it here 745d033

---

The GA job failed. I think, to publish generated content to gh-pages we will need to switch the manual git push in the upload script with dedicated action, eg. https://github.com/peaceiris/actions-gh-pages

The upload-script.sh is removed, then the ./.github/actions/generate-publish-do is updated to run these steps

gil/.github/actions/generate-publish-doc/upload-script.sh

Lines 21 to 25 in 745d033

	rm -r develop
	mkdir -p develop/doc
	cp ../index.html develop/
	cp ../doc/index.html develop/doc
	cp -a ../doc/html develop/doc/

but copying everything to ./public directory from which the new docs are deployed with the action, as per the https://github.com/peaceiris/actions-gh-pages

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public

[gopi487krishna]

@mloskot Sir is creating a PAT on your end not possible?

[mloskot]

It's possible, but I'd prefer to ride on giants shoulder - if I can remove scripts replacing them with simple 3 lines, then it's my preference, less code to maintain the better. Don't worry I'll sort it out. Thanks

[gopi487krishna]

@mloskot Yup you are right sir. I looked at one of the stack overflow posts to see if organizational access tokens can be created, as it turns out its not implemented for organizations at all. So a member of the organization used to typically create a PAT to do it . This as the first comment in the answer says is not a good way to do stuff and instead relying on GITHUB_TOKEN is the best thing

https://stackoverflow.com/questions/31159275/how-do-i-generate-the-github-oauth-token-for-organization-accounts

[gopi487krishna]

@mloskot I can do it by the evening if you want sir. I think its simple to do it. We have to only remove the staging,commiting and pushing part from the upload script and we can set the publish_dir directly to the temporary directory and boom the thing works

[mloskot]

@gopi487krishna Help and contributions are highly appreciated, so if you want to give it a go, please do.