expand documentation fields

[bcoca]

Proposal: expand documentation fields

Author: Brian Coca <@bcoca>

Date: 2017/03/-1

• Status: New
• Proposal type: docs
• Targeted Release: 2.4
• Estimated time to implement: 1 day

Motivation

Provide more information while requiring authors to type less

Problems

Types are unclear in some cases, in others we have authors repeat a lot of 'formulaic' documentation. Many plugins rely on configuration and we don't have a good way to expose that to user currently.

Solution proposal

• Add 'type' field to current docs, could be one of suported types 'bool', 'list', 'dict', 'integer', 'str', etc. This would allow us to use a generic language describing types and in the case of booleans provide the 'choices' section vs having authors copy and paste it 100s of times.

• Add config/env_vars/hostvars sub sections, for 'options' that allows specifying config/env var settings that affect the plugin

• new Deprecated field that has both version and description, version denotes when it will be removed, despcription should contain why and alternatives.

short example of ssh connection plugin:

DOCUMENTATION:
    name: ssh
    plugin_type: connection
    short_description: connect via ssh client binary
    description:
        - This connection plugin allows ansible to communicate to the target machines via normal ssh command line.
    author: ansible (@core)
    version_added: historical
    options:
       _host:
            description:
                - hostname/ip to connect to.
            default: inventory_hostname
            vars:
                 - name: ansible_host
                 - name: ansible_ssh_host
       port:
            description:
                - Remote port to connect to.
            ini:
               - section: defaults
                 key: remote_port
                 default: 22
            env:
               - name: ANSIBLE_REMOTE_PORT
            vars:
               - name: ansible_port
               - name: ansible_ssh_port
       remote_user:
            description:
                - User name with which to login to the remote server, normally set by the remote_user keyword.
                - If no user is supplied, Ansible will let the ssh client binary choose the user as it normally
            ini: # in future we might add yaml: for yaml configuration files
               - section: defaults
                 key: remote_user
            env:
               - name: ANSIBLE_REMOTE_USER
            vars:
               - name: ansible_user
               - name: ansible_ssh_user
                 deprecated:
                         version: "2.7" # "removed in" version
                         why: This option is not really deprecated, this is a test
                         alternatives: use ansbile_user instead

Dependencies (optional)

Not really a dependencies but related PRs:

• https://github.com/ansible/ansible/pull/22796 (expand embeded docs to more plugins)
• https://github.com/ansible/ansible/pull/21171 (add subspec for list/dict types to have further validation)

Documentation (optional)

Requires writing plugin docs ...

Additional

• possibly allow for 'long names' for types in future string/str, dictionary/dict to improve readability, brews complexity and same can be overloaded for aliases so some team members dislike this (-1 x2)

[bcoca]

another example:

DOCUMENTATION:
    author:
        - Jan-Piet Mens (@jpmens)
    name: etcd
    plugin_type: lookup
    version_added: "2.1"
    short_description: get info from etcd server
    description:
        - Retrieves data from an etcd server
    options:
        _raw:
            description:
                - the list of keys to lookup on the etcd server
            type: list of strings
            required: True
        _etcd_url:
            description:
                - Environment variable with the url for the etcd server
            default: 'http://127.0.0.1:4001'
            env:
                - name: ANSIBLE_ETCD_URL
        _etcd_version:
            description:
                - Environment variable with the etcd protocol version
            default: 'v1'
            env:
                - name: ANSIBLE_ETCD_VERSION
EXAMPLES:
    - name: "a value from a locally running etcd"
      debug: msg={{ lookup('etcd', 'foo') }}
RETURN:
    _list:
        description:
            - list of values associated with input keys
        type: strings

In this case etcd takes direct paramters via _raw but indirect configuration via 2 env vars.

[abadger]

I'd change lookup: etcd to

type: lookup
name: etcd

With the documentation parser having some compat code for the old way (for modules only). ie: fill in type and name from the yaml if they exist. If type is empty, look for "module: foo" and set type = "module". if type is module and name is empty, also set name = "foo".

[bcoca]

the plugin_docs PR implemented it this way, we just have to update it to deal with change, though i would avoid 'type' as it is overloaded everywhere, aside from being a python reserved keyword

[grastogi23]

Just noticed it in the contributor conference. I would like to propose adding one more or couple of more attributes

1. readonly: This is one of the attribute that is very handy for documentation. This is something that is very common in networking where a server is up or VIP is up etc. You can enable/disable them as configuration but runtime state is read only.

2. immutable: This is something that can be set only once. There are settings or attributes that cannot be changed. Typically backend will reject those settings but it would be to make it explicit.

3. Ability to describe nested fields. Eg. like swagger specs do.

I would be willing to contribute if you need volunteers

[bcoca]

we already have 'nested' suboptions/subspec .. need to re read what the exact name of key is

[grastogi23]

@bcoca Would love to get more details on it. The only thing i found was passing mention on http://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html

[bcoca]

its been added in 2.4, no good docs on it yet

[bcoca]

done on user side, pushed out with 2.4, many plugin types documented using this format.