Allow documenting option deprecation

[bcoca]

Proposal: deprecated doc key for options

Author: Brian Coca <@bcoca> IRC: bcoca

Date: 2017/06/-1

• Status: New
• Proposal type: doc fields
• Targeted Release: 2.4
• Estimated time to implement: 5mins

Motivation

There is no way to document the deprecation of an option in plugins.

Problems

Will allow authors to document deprecation of options.

Solution proposal

A deprecated key that is composed of the following:

deprecated:
     why: reason for deprecation
     version: version in which this option is removed
     alternatives: description of alternatives to use

Dependencies (optional)

Doc validator needs to permit

[gundalow]

Links to things that will need updating

• https://github.com/ansible/ansible/blob/devel/test/sanity/validate-modules/schema.py
• https://docs.ansible.com/ansible/dev_guide/developing_modules_documenting.html#documentation-block
• ansible-doc to display https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/doc.py
• Online docs updated https://github.com/ansible/ansible/blob/devel/docs/templates/plugin.rst.j2
• Identify any modules that this needs applying to grep '\.deprecat'

Needs to work for suboptions

[gundalow]

Discussed in Core meeting 1st June 2017

• +1 from gundalow, sivel, shertel

The above also believe that the module level deprecations should move to using this

Docs also need updating to point out how to deprecate options in argspec

[gundalow]

Once merged the the following modules will need updating to make use of it:

• network/f5/bigip_pool.py

Feel free to edit this comment to add other modules to the list

[gundalow]

Discussed in Core meeting *st June 2017
+1 from Core thaumos ryansb jctanner gundalow, sivel, shertel
+1 from community: dminca

RESULT: Agreed

bcoca may do this as part of the Ansible config project

[bcoca]

released in 2.4: infrastructure to support it and started using in plugins and config definitions/entries, new module deprecation should use the new format.