render module documentation inside collections

[evgeni]

Feature Request

Use Case

Currently, only README.md from a collection is rendered on Galaxy and the DOCUMENTATION from inside any module that is part of the collection is completely ignored.

As discussed with @gundalow during cfgmgmtcamp :)

Proposed Solution

• Render the module docs in a similar way to https://docs.ansible.com/ansible/latest/modules/
• Provide built docs for all versions of the collection, not only latest

Alternatives

None

Implementation

No idea

[evgeni]

related, but not identical to #1937

[gundalow]

Thanks for raising this. Part one, shoukd be live in the next week or two.

Part 2: Versioned docs, hasn't been discussed in detail yet.

[geerlingguy]

@gundalow - Is there any status update on this? We're readying a new release of the Kubernetes collection and I'm realizing that one new module that's been added (k8s_exec) doesn't have any publicly-viewable documentation—right now the only way for a user to know how to use it is via reading the source or using ansible-doc on the CLI (so it's not very google-able).

[gundalow]

Auto-generated docs in docs.ansible.com/collection/NAMESPACE/COLLECTIONS are still a week or two away due to people being off for personal reasons.

As long as BOTMETA.yml and the nwo/scenario files are correct we will generate the docs.

[evgeni]

Does that mean the feature will only be available for migrated collections (those refered to with migrated_to in BOTMETA), and not for new ones? Because that's what my original request was about :)

[geerlingguy]

@gundalow (and @samccann, who I think I mentioned this to in passing): It sounds like the docs on docs.ansible.com will be only for what's in BOTMETA.yml (which means modules from 2.9, but not any new modules in collections), and maybe someday also docs from Automation Hub collections (supported collections).

However, it doesn't sound like there's any plan for documentation from general collections (e.g. anything new) or from new modules in existing collections (e.g. community.general et all)—so this is more critical to figure out.

Otherwise, we'll end up mired in an interminable situation like we had with roles: https://github.com/ansible/proposals/issues/19 (aside: 'ansible/proposals' seems discouraging, only 11% of any issues in that repo result in any action, and there have only been two proposals that had any concrete action in the past year...).

[samccann]

I think the docs pipeline to docs.ansible.com will pick up new modules within a migrated collection. It will reflect all modules within ACD (once it is available). But that still leaves new collections that come out between ACD versions as well as changes to collections, and collections that aren't part for ACD need a way to display the module content.

(and of course the docs pipeline isn't available yet so all migrated content currently has no way to view the docs other than go back to the 'latest' docs for now).

[bcoca]

related https://github.com/ansible/ansible/pull/67928 , current galaxy/ah efforts on displaying docs rely on ansible-doc --json, this adds listing plugins that are documentable, so it should help with the future features.