ansible

Commit Graph

Author	SHA1	Message	Date
Dag Wieers	cd9471ef17	Introduce new 'required_by' argument_spec option (#28662 ) * Introduce new "required_by' argument_spec option This PR introduces a new required_by argument_spec option which allows you to say "if parameter A is set, parameter B and C are required as well". - The difference with required_if is that it can only add dependencies if a parameter is set to a specific value, not when it is just defined. - The difference with required_together is that it has a commutative property, so: "Parameter A and B are required together, if one of them has been defined". As an example, we need this for the complex options that the xml module provides. One of the issues we often see is that users are not using the correct combination of options, and then are surprised that the module does not perform the requested action(s). This would be solved by adding the correct dependencies, and mutual exclusives. For us this is important to get this shipped together with the new xml module in Ansible v2.4. (This is related to bugfix https://github.com/ansible/ansible/pull/28657) ```python module = AnsibleModule( argument_spec=dict( path=dict(type='path', aliases=['dest', 'file']), xmlstring=dict(type='str'), xpath=dict(type='str'), namespaces=dict(type='dict', default={}), state=dict(type='str', default='present', choices=['absent', 'present'], aliases=['ensure']), value=dict(type='raw'), attribute=dict(type='raw'), add_children=dict(type='list'), set_children=dict(type='list'), count=dict(type='bool', default=False), print_match=dict(type='bool', default=False), pretty_print=dict(type='bool', default=False), content=dict(type='str', choices=['attribute', 'text']), input_type=dict(type='str', default='yaml', choices=['xml', 'yaml']), backup=dict(type='bool', default=False), ), supports_check_mode=True, required_by=dict( add_children=['xpath'], attribute=['value', 'xpath'], content=['xpath'], set_children=['xpath'], value=['xpath'], ), required_if=[ ['count', True, ['xpath']], ['print_match', True, ['xpath']], ], required_one_of=[ ['path', 'xmlstring'], ['add_children', 'content', 'count', 'pretty_print', 'print_match', 'set_children', 'value'], ], mutually_exclusive=[ ['add_children', 'content', 'count', 'print_match','set_children', 'value'], ['path', 'xmlstring'], ], ) ``` * Rebase and fix conflict * Add modules that use required_by functionality * Update required_by schema * Fix rebase issue	6 years ago
Dag Wieers	05c6ff79f9	Convert to reduced list of known types (#50010 )	6 years ago
Dag Wieers	baf0ad2309	Docs: Add a "seealso" section to the module docs (#45949 ) * Docs: Add a separate "seealso" section to the module docs to list related modules and/or related references. This clears up the notes section for things that are actual notes. So you can add a section in your module documentation and four types of references are possible. seealso: # Reference by module name - module: aci_tenant # Reference by module name, including description - module: aci_tenant description: ACI module to create tenants on a Cisco ACI fabric. # Reference by rST documentation anchor - ref: aci_guide description: Detailed information on how to manage your ACI infrastructure using Ansible. # Reference by Internet resource - name: APIC Management Information Model reference description: Complete reference of the APIC object model. link: https://developer.cisco.com/docs/apic-mim-ref/ This PR also includes: - Implements ansible-doc support - Implements schema support for the seealso options - Updates to the development documentation - Rename filter convert_symbols_to_format to rst_ify, cfr the existing html_ify and tty_ify filters - This makes the existing template a lot easier to read and fixes the confusion I had myself rereading the template (again). - We fixed the possible suboption types (which was limited to 'bool' only) * Use latest stable instead of devel docs	6 years ago
John R Barker	75407d3e43	Validate DOCUMENTATION.author (#48993 ) * Validate DOCUMENTATION.author Ensure that author line includes a GitHub account	6 years ago
Justin England	0bc5b799a6	Update win_scheduled_task.py (#46720 ) * Update win_scheduled_task.py to document that the duration of a task trigger can be null, which will cause it to run indefinitely - docs update makes use of suboptions * Add a fix for the validate-modules schema	6 years ago
Matt Martz	86e8d21667	Perform full RETURN schema validation in one step, don't try to loop (#46079 )	6 years ago
John R Barker	78201d1c32	Allow removed_in: 2.12 (#45732 )	6 years ago
Toshio Kuratomi	68c60ad307	Change validate-modules for removed modules Removed modules now don't have documentation. Need to account for that when checking them in validte-modules	6 years ago
Matt Martz	01c0446cb5	Add AnsibleModule signature schema, and fix associated issues (#43512 )	6 years ago
John R Barker	d962611528	Allow documentation of module options type (#42285 ) * Allow documentation of module options Pass through the `type` of a modules option so it's displayed on the html module docs * docs	6 years ago
John R Barker	6024a766e9	Allow removed_in 2.11 (#42119 )	6 years ago
John R Barker	fe4368ce15	removed_in: 2.6 is valid (#40399 )	7 years ago
Matt Martz	8980d275a0	Support recursive suboptions schema (#37206 ) * Support recursive suboptions schema * Remove todo line, add voluptuous version constraint	7 years ago
John R Barker	7dfa11cd8a	Notice in 2.6 remove in Ansible 2.10 (#36191 ) Update the list of allowed removed_in for modules	7 years ago
John R Barker	a23c95023b	Module deprecation: docs, scheme and tests (#34100 ) Enforce module deprecation. After module has reached the end of it's deprecation cycle we will replace it with a docs stub. * Replace deprecated modules with docs-only sub * Use of deprecated past deprecation cycle gives meaningful message (see examples below) * Enforce documentation.deprecation dict via `schema.py` * Update `ansible-doc` and web docs to display documentation.deprecation * Document that structure in `dev_guide` * Ensure that all modules starting with `_` have a `deprecation:` block * Ensure `deprecation:` block is only used on modules that start with `_` * `removed_in` A string which represents when this module needs deleting * CHANGELOG.md and porting_guide_2.5.rst list removed modules as well as alternatives * CHANGELOG.md links to porting guide index To ensure that meaningful messages are given to the user if they try to use a module at the end of it's deprecation cycle we enforce the module to contain: ```python if __name__ == '__main__': removed_module() ```	7 years ago
Matt Martz	19ab882790	Fix inconsitencies between code assumptions and schema (#34901 ) * Fix inconsitencies between code assumptions and schema * Address a couple of RETURN issues, where the description was parsed as a dict	7 years ago
Toshio Kuratomi	af2073d057	metadata 1.1 * Add network value to support_by field. * New support_by value, certified * Deprecate curated in favor of certified * Add conversion from 1.0 to 1.1 to metadata-tool * Add supported by Red Hat field to ansible-doc output	7 years ago
John R Barker	5551e87755	RETURNS can include version_added (#25810 )	8 years ago
Matt Martz	2fbfba0ef3	Make Reporter class hold all results, move line/col into results, and out of message (#24127 ) * Make Reporter class hold all results, move line/col into results, and out of message * Move line/col out of message for YAML parser errors * We have lineno for the DOC var, use it for YAML parser errors * Remove valdiate-modules files from legacy-files * pep8 indentation fixes * Add todo for line/col in _validate_docs_schema	8 years ago
Andrea Tartaglia	4e4fc9cb4c	Added test for 'RETURN' field in validate-modules (#23322 ) * Added test for 'RETURN' field in validate-modules * print the field being tested. Useful when the RETURN structure is complex. * Fixed schema after CI traceback fail * Fixed list_string_types * Fixed line in 319 code for RETURN	8 years ago
Lumír 'Frenzy' Balhar	9d41aefd71	Add Python 3 support for validate-modules test. (#21195 ) * Improve PEP8 compatibility * Fix Python 3 incompatibility Is prohibited to mutate OrderedDict during iteration through it so is better to add records with error or warning to empty dictionary instead of delete records from copy of dictionary during iterating. * Decode output of subprocess from bytes to unicode. * Add Python 3 support for validate-modules test. Fix #18367	8 years ago
Toshio Kuratomi	eb1214baad	New metadata 1.0 (#22587 ) Changes to the metadata format were approved here: https://github.com/ansible/proposals/issues/54 * Update documentation to the new metadata format * Changes to metadata-tool to account for new metadata * Add GPL license header * Add upgrade subcommand to upgrade metadata version * Change default metadata to the new format * Fix exclusion of non-modules from the metadata report * Fix ansible-doc for new module metadata * Exclude metadata version from ansible-doc output * Fix website docs generation for the new metadata * Update metadata schema in valiate-modules test * Update the metadata in all modules to the new version	8 years ago
John R Barker	04e816e13b	Stricter module documentation validation (#22353 ) Raise the bar for module `DOCUMENTAION` This validator update was used to find the issues in https://github.com/ansible/ansible/pull/22297/files Validation * Updated Validation and docs to enforce more (items fixed in https://github.com/ansible/ansible/pull/22297/files) * Use `suboptions` to document complex options * Validate module name * Validate deprecated modules have correct ANSIBLE_METADATA Module Documentation Generation * Document `suboptions:` Example https://gist.github.com/gundalow/4bdc3669d696268328ccc18528cc6718 * Tidy up HTML generation (valid HTML, no empty lists, etc) Documentation * Clarify the steps for deprecating a module * Use correct RST headings * Document `suboptions:` (options) * Document `contains:` (returns) Details The aim is to get this (and corresponding module updates) complete by the time `devel` becomes `2.4`, as this allows us to raise the bar for new modules Example `suboptions` https://gist.github.com/gundalow/4bdc3669d696268328ccc18528cc6718 The aim is to get this PR integrated into `devel` before we branch `stable-2.3`, this will allows us to: * Raise the bar for new modules in 2.4 * Ensure the generated module documentation for 2.3 and higher is improved, important as we will be doing versioned docs moving forward.	8 years ago
Matt Martz	829c0b8f62	Update validate-modules (#20932 ) * Update validate-modules * Validates ANSIBLE_METADATA * Ensures imports happen after documentation vars * Some pep8 cleanup * Clean up some left over unneeded code * Update modules for new module guidelines and validate-modules checks * Update imports for ec2_vpc_route_table and ec2_vpc_nat_gateway	8 years ago
John Barker	ef06b5501c	Port sivel/ansible-validate-modules into Ansible	8 years ago

25 Commits (96549bf6ff4ef485c627ec5818423961cb55fa59)