extend ansible-doc to more than modules

[bcoca]

Proposal: extend ansible-doc

Author: Brian Coca <@bcoca>

Date: 2016/11/34

• Status: New
• Proposal type: core design
• Targeted Release: future release
• Estimated time to implement: 5 days

Motivation

Provide better 'command line' access to docs for plugins and roles (also plays?)

Problems

• You don't always have the role/plugin webpage available, so being able to use ansible-doc to browse the docs can be useful

Solution proposal

• modify ansible-doc to read role and plugin docs

Dependencies

• create specs for role and plugin docs (aside from modules, which are only ones that currently have)
• actually document plugins and roles

[drybjed]

Role could have an URL for its documentation included in meta/main.yml, this would solve the issue of how the documentation should be maintained. There could also be a big shiny "Documentation" button on Ansible Galaxy.

[bcoca]

We already have facilities for documentation in the role (readme and meta/main.yml), having a link does not help for the problem case of not having browser/internet access.

[geerlingguy]

Ooh, CLI docs... :)

Much less use of Dash and Google when doing playbooks would be a win for my productivity. Even if it just gave the table of options for a given module, it would save me a lot of time.

[drybjed]

@bcoca I'm sorry, but the README.md file is just not enough to properly document roles. Case in point, check documentation of the debops.pki role - do you expect all of this to be squeezed into README file? I see the role README as an introduction and explanation of what the role can be used for, not for detailed documentation.

[bcoca]

No, i expect it to be a starting point, still trying to think on how to best document roles and 'non module' plugins.

[geerlingguy]

@drybjed - For the majority of roles, though, a separate docs site isn't really required... there are some roles for which it's helpful, but maybe 90% of the roles I use have 5-10 variables that are meant to be tweaked, and require little in the way of extra explanation (or link off to underlying software's documentation for more advanced use).

Not to say it wouldn't be nice to have a 'docs_url' variable to set or something like that, but I do think that level of role documentation may be an exception rather than the norm.

[bcoca]

closing as 'completed' as all basic facilities are there, just need to convert some plugin types and that will be done over time.