Adding community-contributed examples to docs or a github repo

[samccann]

Summary

This idea came up in the Documentation Working group meeting. Based on the docs survey from the beginning of this year, our readers are looking for more examples.

One specific area mentioned was more and better templating examples. So the idea came about that maybe we can create an area for community-contributed examples to expand on our existing documentation. This could either be on docs.ansible.com/ansible, or within a github repo. The docsite would in theory be more 'findable', but we wanted to open this up to community discussion to see if it's something people would want to contribute to, and how best to make this easy and yet verifiable that the examples work.

This is the docs survey feedback for the specific template example request - ansible/ansible#75507

[Andersson007]

A random brainstorming idea:

• we could create a repo called say community-examples with CI configured or we could create a directory called, say, community-examples in community-docs (there are some contributor documents in the root. We could move them to another directory)
• set up CI there + a test target
• if a contributor add an example, they have to add integration tests that reproduce the example (add a dedicated file and include it in tasks/main.yml) checking the output with assert or something

Later on, provided that there are enough examples, if we decide to have them somewhere on docs.ansible.com, we could

1. move pages to the docsite
2. if new examples appear, they should be tested in that repo first (or we could move the test target to ansible/ansible)
3. if tests pass, we'll add them to the docsite

[samccann]

Brought up in the community meeting - jillr/aws has some examples they can donate to the cause ;-) and https://github.com/ansible-community/sphinx-ansible (goneri) has a way to pull these examples from a github repo into docs.ansible.com.

sivel has a way to test as well - https://ansible.sivel.net/test/ (allows Ansible filters/lookups)
cidrblock mentioned - https://td4a.codethenetwork.com/ as well that can test jinja2 expressions

PR creators on this new examples repo could use those to test/validate before opening a PR (which will then run the embedded CI)

Next steps:

• decide which repo to use for these examples
• set up CI for new additions
• try one or two to make sure the system works
• put out a call for contributions (bullhorn etc)
• update the core docs to point to the new content (assuming it gets hosted elsewhere)
• try out the sphinx-ansible extension to pull those examples into the docs

[Andersson007]

So i propose the following repo name options to create under https://github.com/ansible-community:

• community-examples
• ansible-examples (notice that there's a repo with the same name in https://github.com/ansible).

What does everyone think? Any other options?

[samccann]

My thought is to go with community-examples because it emphasizes where these come from. Some of them may not be the 'best' way to solve a problem, but so long as they pass CI, we can still give them a home there. I'll try to revive this discussion in the DaWGs meeting this week.

[samccann]

We discussed this at the DaWGs meeting and voted to use community-examples for the repo name, and probably put the template examples under a directory in case we decide to add more categories of examples in the future.

[gundalow]

My thought is to go with community-examples because it emphasizes where these come from. Some of them may not be the 'best' way to solve a problem, but so long as they pass CI, we can still give them a home there. I'll try to revive this discussion in the DaWGs meeting this week.

+1

We should also define the directory structure so:

• Easy for people to find
• Allows CI testing only if that specific example changes

[Andersson007]

How about the following workflow?
I'll create a repository ansible-community/community-examples with the following basic structure
(can be redefined later):

.
├── examples
│   └── core
│       └── example1.yml -> ../../tests/integration/targets/core/tasks/example1.yml
└── tests
    ├── integration
        └── targets
            └── core
                └── tasks
                    ├── example1.yml
                    └── main.yml

Where core is a directory which includes examples for core modules / plugins

The following will be described in detail in the repo's README.md.

When someone wants to add an example which involves only core modules/plugins, they create a PR which:

1. Creates a test file in the core target, say tests/integration/targets/core/tasks/example2.yml with comments, asserts, etc.
2. Imports this file in tests/integration/targets/core/tasks/main.yml.
3. Creates a symlink to tests/integration/targets/core/tasks/example2.yml in examples/core.

Then we'll set up GHA.

What do you think? If it sounds sensible, I could implement this.

[Andersson007]

I created the community-examples repo.

The next step is to get real examples.
Is anyone interested in giving us a couple of examples worthwhile having on docs.ansible.come? Feel free to create an issue in https://github.com/ansible-community/community-examples

[samccann]

@felixfontein @Andersson007 since this is being implemented (nice tag!) should we close the issue?

[felixfontein]

Since there is a new tracking issue for this (ansible-community/community-examples#2) I think we can close this one.