Should docs be included in collection and Ansible package tarballs?

[samccann]

For the collection tarball - including the /docs folder adds space, especially for those collections generating module/plugin rst files within the collection /docs folder to provide documentation linked to from the Galaxy readme (an interim fix until Galaxy displays module docs).

• do we expect users to read the raw .rst files included?
• do they solve for the scenario of a site that has no internet access so only the local .rst files provide any documentation of the collection?

If we decide to remove them, then:
Add build_ignore in galaxy.yml for /docs (and in collection_template)

Proposal for Ansible package at large - even if we decide to keep the /docs folder within the collection tarball, we could remove all .rst from the Ansible package itself (along with the main Ansible .rst files in docs/docsite/rst for all the Ansible user/developer guide content) A similar story wherein the Ansible package is large and this would trim down the size of it. We can create a separate ansible-documentation package that includes the .rst files and the generated HTML for offline reading.

We'd ❤️ your feedback!

• Under what circumstances would this feature be useful to you?
• Is there anything you expected to see, but didn't?
• Does this have a direct negative impact on your user or developer workflow in any way?
• Do you use the RST or HTML docs included in ansible-base or any of the collections directly, rather than via docs.ansible.com?

[gundalow]

Collection docs/ directory sizes in KiB:

4	f5networks/f5_modules/docs
8	openstack/cloud/docs
12	infinidat/infinibox/docs
28	openvswitch/openvswitch/docs
60	ibm/qradar/docs
64	frr/frr/docs
72	dellemc/os6/docs
80	splunk/es/docs
100	community/zabbix/docs
100	dellemc/os9/docs
112	wti/remote/docs
152	ansible/posix/docs
160	cyberark/pas/docs
316	cisco/asa/docs
336	dellemc/os10/docs
416	ansible/netcommon/docs
700	ansible/windows/docs
844	junipernetworks/junos/docs
904	vyos/vyos/docs
1044	amazon/aws/docs
1224	arista/eos/docs
1408	community/windows/docs
1480	cisco/iosxr/docs
1504	cisco/ios/docs
1832	netbox/netbox/docs
2760	cisco/nxos/docs
3200	community/vmware/docs
5768	community/aws/docs

[goneri]

I would also prefer to keep these auto-generates files out of the tarballs... and from the git repository too. Where can I get update regarding the Galaxy/docs integration?

[geerlingguy]

Issues to follow:

• [collection] How to display a role documentation ?
• render module documentation inside collections
• Docs: metadata for role documentation

[rockaut]

For me a clear removal imo. Never ever used the provided docs. Always gone online.

[felixfontein]

Having a separate tarball for docs would be awesome, especially one including the .html files. Sometimes people have to work offline or in restricted environments, or have a very slow internet connection. But they really don't have to be in the main tarball.

[wtinetworkgear]

The problem I have in general when de-coupling things that belong together is that over time they become out of sync and in a very short time, very confusing for a user trying to debug or setting up for the first time.
I know you can look online, but in a console only environment when i don't have the browser handy, its nice to have everything installed and up to date.
As long as there is a way to keep things in sync, i have no problem separating them.

[maxamillion]

I for one really enjoy having the docs included because historically I use ansible-doc for reference exponentially more than the docs website and would like to see that functionally continue forward for Collection delivered content.

[gundalow]

ansible-doc will continue to work. This is just about removing the RST files from the Collection tarball (https://github.com/ansible-collections/ansible.netcommon/tree/main/docs)

They will continue to be visible in GitHub via https://github.com/ansible-collections/ansible.netcommon/tree/main/docs

[maxamillion]

@gundalow ansible-doc won't work if the RST files aren't in the tarball because if that's the case, when I install the collection and then run ansible-doc -l it won't be accurately reflecting the installed content available on my control machine nor will I be able to reference the documentation of the contents within the Collection with ansible-doc locally on my machine. I think if we're going to make this change, we might as well remove ansible-doc from Ansible because it would become so crippled it would be useless.

[gundalow]

I can't test this right now, though I'm fairly certain ansible-doc just reads the module or plugins DOCUMENTATION block from inside the module or plugin Python file.

[felixfontein]

ansible-doc has absolutely nothing to do with .rst files included or not included in collections. It uses the DOCUMENTATION block in the modules and/or plugins. (I've touched that code often enough this year, believe me :) )

[abadger]

A couple tangential thoughts, not directly answering the question... what we decide here shouldn't make things worse for these situations but does not need to address them itself:

• A system packager would probably want to move all of those docs to /usr/share/docs instead of leaving them in the collection directory. Since the ansible package is a conglomeration of multiple collections, system packagers probably haven't seen that there are docs embedded in the collection directory yet and will find it slightly painful to move them once they do see that.

  • Relevance: stripping the module docs from the collection directories in the ansible tarball build and adding them to a separate package should make this easier for system packagers to put in their preferred location. Stripping the docs and not putting them into another tarball would make it harder for system packagers.

• There's a related issue about how we're going to move the guides into collections. If the guides and the pre-generated module docs that are shipping inside of collections both end up in the collection tarball and we have no way to differentiate them, then we'll end up duplicating the plugin doc information in two places when we build them.

  • Relevance: We may need to consider having separate directories for the guides and the pre-generated plugin docs. Would we want to strip both of those from the collection tarballs?

[abadger]

Regarding whether it's nice to have docs inside of the collection tarballs: I don't think that galaxy currently allows for multiple tarballs per release. So someone who gets a collection from galaxy will need any non-plugin offline documentation (the guides that we've talked about moving out of the ansible-base tarball) available in the collection tarball. Certain classes of plugins (modules, for instance) have offline documentation available via ansible-doc so it's not the end of the world if those docs are left out of the collection tarballs.

[samccann]

After a longer discussion, it seems this may not be worth the effort. To explain - the initial goal was to reduce the Ansible tarball since it has grown to about 29MB. Removing the docs from this only brings it down to 28MB (7% reduction). At this point, it doesn't seem worth it since we'd have to create and maintain separate packages and determine if it will break GPL licensing etc (that is, we don't get enough size reduction to make the additional work with the effort).