Collection specific Developer Guide in ansible

[mariolenz]

Summary

I wanted to update the Developer Guide for community.vmware which still exists in ansible itself (see ansible/ansible#77585).

I was asked if I could move this to the collection. This makes sense to me and I'll try to do it, although I might need some help there and ideally a working example. Anyway, I've seen there is content specific to other collections, too.

Should we address this? That is, identify the collection specific content still in ansible and open issues in the collection repositories to move it?

Thoughts?

edit:

• Guidelines for Ansible Amazon AWS module development
• OpenStack Ansible Modules
• oVirt Ansible Modules
• Guidelines for VMware module development
• Guidelines for VMware REST module development
• Developing Cisco ACI modules
• Windows module development walkthroug

[felixfontein]

Which parts do you think should be moved to the generic documenation?

[Andersson007]

At the first glance, sounds sensible to me in general - collection specific dev guides should, imo, live in corresponding collections.
Let's maybe split this logically into 2 questions:

1. Should dev guides specific to a certain collection (or maybe saying more general all docs specific to a certain collection, not only dev) live in that collection? Sub-questions:
   a) Should the docs be available for readers as they are? If yes, how easy it would be to implement?
   b) Or they should appear somewhere within docs for the collection? (so the path for readers will change)
2. Provided that the answer to question 1 is positive, which files should be moved and to where.

What do you, folks, think?

[mariolenz]

fyi: ansible-collections/community.vmware#1294

[mariolenz]

1. Should dev guides specific to a certain collection (or maybe saying more general all docs specific to a certain collection, not only dev) live in that collection? Sub-questions:
   a) Should the docs be available for readers as they are? If yes, how easy it would be to implement?
   b) Or they should appear somewhere within docs for the collection? (so the path for readers will change)

I don't think it makes much sense to still have collection specific stuff (including docs) in https://github.com/ansible/ansible. And it makes more sense to have the collection specific documentation all in one place. So 1b) if you ask me.

For example, all docs specific to community.vmware should apear under community.vmware.

2. Provided that the answer to question 1 is positive, which files should be moved and to where.

I don't know where there is collection specific documentation scattered around the place, but I found at least some Developer Guides in docs/docsite/rst/dev_guide/platforms/ that look collection specific.

[mariolenz]

Which parts do you think should be moved to the generic documenation?

Well, everything that's generic. That is documentation dealing with ansible-core or ansible at large. If it's specific to a collection, it should go there- both in the repo and the place where it's shown in the documentation.

I'm not sure if there's stuff specific to a collection namespace. That would be a bit tricky because namespaces don't have a repo. So for technical reasons we might have to keep this in https://github.com/ansible/ansible.

Interesting question: What documentation would the ansible-core developers accept into https://github.com/ansible/ansible? If they say "no, that doesn't belong here" and there's already similar content, it should be moved somewhere else. Just to have a clear policy and be fair to everyone, you know ;-)

Btw: Thanks for your demo on collection docs at the Contributor Summit 2022.04 @felixfontein! It was most interesting and helped me a lot with ansible-collections/community.vmware#1294.

[Andersson007]

I'm personally OK with moving guides living in docs/docsite/rst/dev_guide/platforms to corresponding collections:

1. If there are volunteers
2. who'll move them to the collections and
3. who'll make them appearing under corresponding subdirs of https://docs.ansible.com/ansible/devel/collections/community

[mariolenz]

@Andersson007 I'm still working on moving the Developer Guide for community.vmware to the collection. When that's done, I would have a look at the other collection specific documentation in docs/docsite/rst/dev_guide/platforms/.

I won't promise to do everything myself, but at the very least I will open issues in the collections asking them to do it.

[samccann]

FWIW - we made the decision some time ago that collection-specific docs must move to their collections. They should all be removed from ansible/ansible.

The infrastructure for this is already in place see here for some rough instructions on how to move them. And here is one collection where I opened an issue. I haven't done it yet for the rest and would love help if anyone is up for it.

So if/when someone opens a PR in ansible/ansible to update a collection-specific guide is usually when I catch it and say please move to the collection. It's not great to do it that way so would definitely want to open issues on each collection to get them moved.

The tricky part is those guides that overlap more than one collection. For now, I don't have a great solution in mind for those.

[mariolenz]

@samccann

I haven't done it yet for the rest and would love help if anyone is up for it.

I'm working on the community.vmware dev guide (you might want to have a look at ansible/ansible#77723) and would also have a try at vmware.vmware_rest when this is done. For the rest, I would at least open an issue in the collection repos. Maybe I would even create a PR there, but I won't promise anything.

[samccann]

amazon.aws is in the process of moving their dev guide to the collection - ansible-collections/amazon.aws#787. Once it shows up in a release, we can stub it out on ansiblle ansible, so not marking it done yet in the checklist above.

stub pr -ansible/ansible#77752

[samccann]

openstack module dev guide has already been stubbed out and moved (though not to the collection, but that is their choice I guess). Marking that done.

[samccann]

ovirt has its own dev guide now as well so stubbed out the old one with a pointer. Marking it done.

(samccann swoops in and does plucks all the low-lying fruit on this one!)

[samccann]

Opened an issue for Cisco ACI guide and windows module dev guide migrations.

[mariolenz]

I've opened a PR to move the vmware.vmware_rest dev guide to the collection: ansible-collections/vmware.vmware_rest#330

[mariolenz]

As @felixfontein pointed out, this documentation even shows up in ansible-core.

I think this is wrong. At the end of the day, I think it would be better to remove this stuff and live with broken links. What do you think?

[samccann]

I can remove them from core I think. Let me experiment a bit with that one.

[samccann]

They should be removed from core on the next nightly build.

[mariolenz]

I think I'll close this topic. We're more or less done, apart from the Cisco ACI stuff. I've opened CiscoDevNet/ansible-aci#298 but it's still not merged, they seem to ignore it.

@samccann My advise is to simply remove the Cisco ACI documentation from the ansible-core dev guide, even if there's no alternative dev guide in the Cisco ACI collection you could link to. If Cisco doesn't care, why should you? At the end of the day, it's their problem...

[felixfontein]

@samccann My advise is to simply remove the Cisco ACI documentation from the ansible-core dev guide, even if there's no alternative dev guide in the Cisco ACI collection you could link to. If Cisco doesn't care, why should you? At the end of the day, it's their problem...

👍 to that. I've added another ping to the PR, maybe it helps, but i not, we should really just continue with removing that guide.