feat(gh-actions): automates docs update based on README changes

[bartoszmajsak]

Short description of what this resolves:

Removes outdated sections in the docs and adds extra gold-plating to the process :D

Changes proposed in this pull request:

• docs update
• automated sync between README and adoc docs.

[aslakknutsen]

Am I understanding this correctly that any update to README will trigger a bot commit to update the adoc in the same PR?

Why not move it from README during 'publish'?

[bartoszmajsak]

Am I understanding this correctly that any update to README will trigger a bot commit to update the adoc in the same PR?

That's what is happening, correct. The idea is that README is easier to get contributions to as it's always visible on the main repo view.

It also shares the same info as we have in our official docs (and it's sourced for operator description as well). So I thought this little automation will keep it up-to-date nicely.

Why not move it from README during 'publish'?

Then docs publishing job (I guess that's what you mean by publish) will result in another commit on the main branch which in effect will trigger another publish with updated sources... :) So I was thinking it's better to keep it scoped in the PR. This way we have one commit and one docs publishing process.

[aslakknutsen]

I just meant as part of the "doc generation" phase. When we get the Tekton Tasks included, or include the other part of the README, or run the ike cli stuff...

[bartoszmajsak]

I just meant as part of the "doc generation" phase. When we get the Tekton Tasks included, or include the other part of the README, or run the ike cli stuff...

Fair point, that way we also avoid potentially changing the "wrong docs" (those which are automatically included).

There are is one thing which we should consider though - we are losing a chance to preview. We just assume markdown will be converted to nicely looking asciidoc (that's already a problem with cli help generation but this one is somewhat stabilized output).

[aslakknutsen]

@bartoszmajsak We could make a simple Make target to 'generate doc stuff' couldn't we? It would be a manual step during writing but... We have had plans for a per PR doc build haven't we? :)

[bartoszmajsak]

@bartoszmajsak We could make a simple Make target to 'generate doc stuff' couldn't we? It would be a manual step during writing but... We have had plans for a per PR doc build haven't we? :)

We have tons of plans :D I will rework this to be done the same as all the others, as an asciidoc directive.

Preview is another story though.

[bartoszmajsak]

Converting back to draft as it needs rework based on the discussion.