Modules or plugins using doc fragments from other collections are not shown at all. (Doc fragments from ansible-core or from the same collection work.)
The Documentation tab is grouped by modules / plugins, and “plugins” contains things like doc fragments and module utils. This is pretty much useless.
The extra docs are also not rendered in Galaxy. In community.openwrt, like many other collections not in the ACP, those docs are being published directly to Github. Being a new collection, a lot of things are changing quickly, including those extra docs, and we currently have no trivial way of publishing multiple versions of those docs.
It would be wonderful to have that in Galaxy. The other option we have been considering is publishing directly to readthedocs.io.
We often see Collection maintainers wanting to get into the ansible package, purely to good quality HTML docs, rather than them being useful to the majority of Ansible users.
One thing @oranod and I have talked about is ripping out all the docs build/rendering code from Galaxy (and Automation Hub) and just using the upstream community docs build scripts. They are the most feature rich and well tested. I know @oranod has some ideas about a how we could have all collection docs built this way.
So please do share your ideas what what you’d like to see done.
The blunt answer is: I would like to have the ability of publishing docs the same way that packages in ACP do (with versioning in the rendered HTML, with extra docs, the whole shebang), without having to add the package to ACP.
Particularly in the case of community.openwrt, I don’t see it ever going into the ACP for many reasons but especially for the fact that the modules are not written in Python, so this would be a need for that collection for the foreseeable future.
I guess one could also use ReadTheDocs to publish the documentation, since they’re taking care of version selection. I haven’t tried that, but I guess it shouldn’t be too hard to set up either.
As @gundalow alluded to, and as it came up at CfgMgmtCamp, we’re really interested in using the new docs landing page and RTD hosting to sort of bypass some of the docs rendering issues on Galaxy.
We’re working on putting together all the notes from Contributor Summit and outlining work that we’ve identified for the Community and Partner Engineering team. One of those things will be some wireframes and maybe a POC to show how this might work.
It could be quite similar to the ecosystem band that takes you to the ecosystem page. The difference in what we’re thinking is the focus on collections with sort of overlay on Galaxy.
We have a js button on docs.ansible.com that copies pip install ansible to your clipboard. It is easy to add buttons to install collections.
I’m not sure if there is a limit to the number of subprojects we can add to the ansible namespace in Read the Docs. But if collections publish to RTD it is possible to add them as a subproject so the docs are available under docs.ansible.com.
The end result should give us a convenient way to highlight collections, increase discovery, and do other things like provide clear indicators of content quality.