Docs add examples page

[rklonner]

Resolves #266

This is the initial version as I could imagine an Examples page. I had a look at Kargo in the last weeks and was inspired from their Examples page which I like, especially that the end user is provided with some context on what the target is and how the tool supports that to make it easier to digest.

If the examples are named like the branches we can reuse that in the instructions to run the examples locally and just change the TARGET_BRANCH name with it. Then we do not need to "hardcode" the commands for the examples if they do not contain special parameters or flags.

For that it would make sense that we name the example branches in a uniform way, what do you think? As least for the prefix and topic. And we maybe could rename them from the numbered version "helm-example-1" to "example-helm-external-chart" to indicate the purpose.

example-<topic>-<purpose>

example-helm-external-chart
example-helm-internal-chart
example-kustomize-
example-applicationset-...

maybe we find a shorter prefix then "example-". I assume removing it completely will make it hard to browses through actual feature branches.

Here is how it looks like rendered:

[rklonner]

@dag-andersen : What do you think about the basic structure? Do you have some input how to improve it or if you imagine it differently? Or is this already close to something we could merge?

[dag-andersen]

@rklonner I think the basic structure looks good. I'd like to add a section that shows what the output might look like (similar to here).

Also did we decide on a naming standard? The PR i opened was called demonstrate-appset-refactoring but here you refer to it as example-applicationset-refactoring

[rklonner]

I'd like to add a section that shows what the output might look like (similar to here).

Sounds good.

Also did we decide on a naming standard? The PR i opened was called demonstrate-appset-refactoring but here you refer to it as example-applicationset-refactoring

No we did not - yet. This PR was created in parallel to the new example, it is not fixed yet. Was not sure if therefore this PR should be in draft state or if we add it directly during the discussion.

In my initial comment of this PR I raised the naming convention topic to discuss with you and maybe find a scheme for easier reference:

For that it would make sense that we name the example branches in a uniform way, what do you think? As least for the prefix and topic. And we maybe could rename them from the numbered version "helm-example-1" to "example-helm-external-chart" to indicate the purpose.

example--

example-helm-external-chart
example-helm-internal-chart
example-kustomize-
example-applicationset-...
maybe we find a shorter prefix then "example-". I assume removing it completely will make it hard to browses through actual feature branches.

What is your opinion on that?

[dag-andersen]

@rklonner

Yes, discussing similar things across multiple PRs and Issues quickly becomes overwhelming. At least I find it a bit hard to figure out what conversations are depending on each other.

I think it would be easier for you if you simply create the branches you would like (on your own fork) and then submit the pull request containing references to your own repo (using the branch names you like).

Like:

BRANCH_NAME = <your-preferred-branch-name>
git clone https://github.com/rklonner/argocd-diff-preview base-branch --depth 1 -q $BRANCH_NAME

This way you can test your submitted examples, and I can test your example on the PR. I am even willing to merge the PR with references to your fork.

And after the PR is merged, I will simply recreate the branches on this repo (maybe under a different name if I don't like the name you picked) and then update the references in the docs.

I think this should be pretty easy and remove dependencies between our work, and also we don't necessarily need to decide on stuff like naming :)

Do you think that makes sense?

I just feel bad for your great work being held back by my decision-making or creation of stuff.

[dag-andersen]

What is your opinion on that?

if your new section is about use cases the naming could start with use-case-<something> or demo- or ex-.

It is hard for me to tell at this point, since i don't know how many examples there is going to be :)

[rklonner]

This way you can test your submitted examples, and I can test your example on the PR. I am even willing to merge the PR with references to your fork.

And after the PR is merged, I will simply recreate the branches on this repo (maybe under a different name if I don't like the name you picked) and then update the references in the docs.

Do you think that makes sense?

Yes this is fine for me, let's try that out for the next example. For this PR it is not too important.

I just feel bad for your great work being held back by my decision-making or creation of stuff.

Thanks for that. I am sure we will find a way. I did not want to overcomplicate things, I just had the feeling that you started with a naming scheme already by using branch names like example- and topic-exmaple. As I would also refer to some of those (e.g. external helm chart) I wanted to first ask and not working against what you already have 😃

If you say you see the existing examples differently as they also have some purpose in integration tests etc and that for the examples package we make every example standalone this is fine for me and we can do a new scheme here or start with even leaving the prefix away if you do not mind.

Regarding

I'd like to add a section that shows what the output might look like (similar to here).

I think it is not necessary that the tool output is shown in this example page. I would assume that persons entering this page did the quick demo already. If you want I can add this as a first sentence like

If you are new to the tool your may try out our Demo first and then come back for looking at other examples.

So to summarize what I would do to make this PR "mergeable":

• rename the use case folder appset-refactoring -> applicationset-refactoring
• rename the branch demonstrate-appset-refactoring -> applicationset-refactoring
• remove the external helm chart example here and create a standalone example in the use-cases folder and make a new PR
• extend the examples page one by one with new examples in dedicated PRs to bring changes faster to production documentation

Would that work out for you @dag-andersen ?