cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
43523 commits 47 branches 390 tags 440 MiB
Commit graph

25 commits

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
 2019-02-15 10:57:45 +10:00
Dag Wieers
05c6ff79f9 Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
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
 2018-12-12 14:19:58 -06:00
John R Barker
75407d3e43
Validate DOCUMENTATION.author (#48993) 
* Validate DOCUMENTATION.author

Ensure that author line includes a GitHub account
 2018-11-21 17:29:29 +00:00
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
 2018-10-11 13:16:25 -05:00
Matt Martz
86e8d21667
Perform full RETURN schema validation in one step, don't try to loop (#46079) 2018-09-24 16:38:04 -05:00
John R Barker
78201d1c32 Allow removed_in: 2.12 (#45732) 2018-09-17 10:54:00 -04:00
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
 2018-08-24 15:37:13 -07:00
Matt Martz
01c0446cb5
Add AnsibleModule signature schema, and fix associated issues (#43512) 2018-07-31 15:04:22 -05:00
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
 2018-07-05 09:57:58 -04:00
John R Barker
6024a766e9
Allow removed_in 2.11 (#42119) 2018-06-29 09:42:54 -07:00
John R Barker
fe4368ce15
removed_in: 2.6 is valid (#40399) 2018-05-18 15:32:31 +01:00
Matt Martz
8980d275a0
Support recursive suboptions schema (#37206) 
* Support recursive suboptions schema

* Remove todo line, add voluptuous version constraint
 2018-03-09 17:09:58 -06:00
John R Barker
7dfa11cd8a Notice in 2.6 remove in Ansible 2.10 (#36191) 
Update the list of allowed removed_in for modules
 2018-02-14 09:24:18 -08:00
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()
```
 2018-01-30 12:23:52 +00:00
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
 2018-01-15 18:29:20 -06:00
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
 2017-08-15 23:12:08 -07:00
John R Barker
5551e87755 RETURNS can include version_added (#25810) 2017-06-16 20:17:38 +01:00
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
 2017-05-03 10:25:08 -05:00
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
 2017-05-02 09:01:53 +01:00
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
 2017-04-10 07:43:39 -07:00
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
 2017-03-14 09:07:22 -07:00
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.
 2017-03-13 19:49:27 +00:00
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
 2017-02-02 11:45:22 -08:00
John Barker
ef06b5501c Port sivel/ansible-validate-modules into Ansible 2016-10-13 14:36:22 +01:00
Renamed from ansible_testing/schema.py (Browse further)