Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Draft
wants to merge 8 commits into
base: master
Choose a base branch
from

Conversation

bartoszmajsak
Copy link
Contributor

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
Copy link
Member

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
Copy link
Contributor Author

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.

@bartoszmajsak bartoszmajsak added component/docs Component: Documentation kind/enhancement Kind: New feature or improvement skip-changelog Command: used by changelog generator labels Oct 15, 2021
@aslakknutsen
Copy link
Member

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
Copy link
Contributor Author

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
Copy link
Member

@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
Copy link
Contributor Author

@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 bartoszmajsak marked this pull request as draft October 20, 2021 14:59
@bartoszmajsak
Copy link
Contributor Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
component/docs Component: Documentation kind/enhancement Kind: New feature or improvement skip-changelog Command: used by changelog generator
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants