Add update docs action

[Confectrician]

This will add an action, which triggers an openhab docs repo action on an openHABian release.
(Or on a manual dispatch of this action via the Github Page.)

Depends on: openhab/openhab-docs#1690

Goal

Transfer latest openHABian documentation to the openhab docs website, when a new release has been published.

Prerequisites

• Doc files have to be in a docs folder
• Articles that should be transferred have to be prefixed with openhabian-
• Images that should be transferred have to be in a docs/images folder
• Images that should be transferred have to be prefixed with openHABian-
• This repository needs a secret named DOCS_REPO_ACCESS_TOKEN with public_repo access to the openhab-docs repository

Workflow

This action will trigger a repository_dispatch event in the openhab-docs repository, when everything is set up correct.
This event will start an action in the openhab-docs repository that fetches the latest openHABian docs contents and copy them into the stable-release openHAB documentation.

@kaikreuzer can we steup a Personal Access Token with the openhab-bot account for this?
The PAT then needs to be stored as a Secret in this repo, with the name written above.
This is needed to trigger events across different repositories.

[ecdye]

@Confectrician why not just do it every time the docs are updated in this repo. It is pretty simple to accomplish by doing something like:

on:
  push:
    paths:
      - 'docs/**'

Unless of course you are concerned about the workflow being triggered too often causing too many refresh's for our build system to handle.

[Confectrician]

Hey @ecdye

This was the procedure, I had a talk about with @mstormi before starting working on this.

Please note that we are talking about the docs "stable version".
Any changes in the meantime will get copied into the snapshot docs trough our regularly Jenkins ci job parallel.

Edit:

So now that i am not on my phone but on a real keyboard:

Build time is also a foctor that may get important at some point.
I have implemented those actions now in a reausable way and want to add some more repos like alexa, google-assistant, vscode and others where this makes sense.

Even with the open source plan of netlify (which hosts our website and docs) we have som limit for the build minutes and we already got warnings in the past, especially when we are near to an openHAB release where many builds are triggered from the openHAB Distro.

We can extend the amount of events at any point, but i think per release is a good point for startign with this.

[ecdye]

Fair enough, I was just curious about the reasoning behind the decision. Perhaps in the future it would be better for a transparency of communication to use the GitHub Team discussions page so that all the maintainers can see and comment.

[Confectrician]

You are totally right. I have to excuse me for this.

But for completeness i have to admit that we started this talk personal on the general assembly event of the openhab foundation somw weeks ago and i just continued on that base within a community message.
So there was no bad intention on this.

[ecdye]

No, problem. To be honest this is a great idea and should be very useful once fully implemented.

[Confectrician]

OK, we are ready.
Token has been placed and the actions on docs repo side are available.

[Confectrician]

I did a test run from openhab-docs repo side and the created PR looks valid.
openhab/openhab-docs#1694

[ecdye]

LGTM, @Confectrician are we ready to merge then?

[Confectrician]

Yes we are.

We should verify if the trigger is working correct after merging by running the action manually.
You should be able to do so in the actions tab after merging.

[Confectrician]

Worked like a charm. Thanks. :)

openhab/openhab-docs#1697