GH action to auto-build documentation for PRs

[jaladh-singhal]

Currently, we have documentation preview option which requires PR author to do manual setup of deploying docs on their fork. The process is difficult for people unfamiliar with GH action and hence if authors can't do it, there's no way PR reviewers can see the built docs online.

We need to automate it by creating a GH action workflow which should trigger on a PR if docs/ files are changed and will build docs and deploy them either:

• on tardis-sn.github.io/tardis/<pr no.> (as @harpolea suggested) or,
• on tardis-sn.github.io/docs-demo/tardis/<pr no.> (what I personally prefer because docs-demo repo can then contain docs of other repos like carsus, etc. besides tardis).

Besides, once the deployment is done, workflow should comment on PR with link to deployed docs and once PR is closed/merged, it should delete the docs related to that PR.

Some Pointers:

• Check config options in https://github.com/peaceiris/actions-gh-pages
• Example of how this idea looks in action is RTD: https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html (see docs for their Docs: Add some details to the User Defined Redirects readthedocs/readthedocs.org#7894 at https://docs--7894.org.readthedocs.build/en/7894/)

Concern:

As @epassaro pointed out,

I think it's not possible because GA does not share secrets with forks, then you can't write in tardis gh-pages.

But we should give this a try considering how useful it will be!

[aribalam]

@jaladh-singhal @epassaro After doing some research on the issue, in my opinion, it is not possible to publish documentation preview on the main site through pull requests. (As @epassaro pointed out, the Github Token does not get shared across forks)

However, I still feel that we can automate a part of the procedure.

I propose that we create a new workflow that will get triggered with a push event (on any branch other than master) whenever it involves a change in the doc files. This workflow will be disabled in the main repository.

The forks will have to enable this workflow. So whenever a doc file is changed in a commit (say, on a branch named new-feat), the workflow will generate a documentation preview in <username>.github.io/tardis/new-feat. So, after making a pull request, the documentation could be previewed through the above URL.

This will remove the need to create new branches and making pull requests to their own forks, as mentioned in the docs.

Moreover, this will also remove the limitation that only a single preview could be made for an entire fork. According to the above method, each branch of the fork (that changed the doc files) will have its own preview (on <username>.github.io/tardis/<branch>).

@jaladh-singhal @epassaro I have tested this method in my own repositories and would like to give this a shot if you all agree to it.

[epassaro]

I think your approach is better than the procedure we currently have. Go ahead with it.