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()
```
* compare arg+aliases between docs and argument_spec
* Add some special handling for the network modules provider options that also appear in the top level arg spec
* Fix error code for bigip_hostname
* Address merge conflicts due to changes in f5 modules
* Update validate-modules ignore based off a clean execution
* Address merge conflicts
* Address renamed module
* Address recent changes to modules
* Add ignore for ucs_ip_pool
* Update aci modules to get more reliable documentation comparison, but not mutating the module_utils aci_argument_spec
* Update ignore.txt after recent aci updates
* Add extra guard to ensure we handle provider special only for network modules
* Address additional changes to modules
* allow shells to have per host options, remote_tmp
added language to shell
removed module lang setting from general as plugins have it now
use get to avoid bad powershell plugin
more resilient tmp discovery, fall back to `pwd`
add shell to docs
fixed options for when frags are only options
added shell set ops in t_e and fixed option frags
normalize tmp dir usag4e
- pass tmpdir/tmp/temp options as env var to commands, making it default for tempfile
- adjusted ansiballz tmpdir
- default local tempfile usage to the configured local tmp
- set env temp in action
add options to powershell
shift temporary to internal envvar/params
ensure tempdir is set if we pass var
ensure basic and url use expected tempdir
ensure localhost uses local tmp
give /var/tmp priority, less perms issues
more consistent tempfile mgmt for ansiballz
made async_dir configurable
better action handling, allow for finally rm tmp
fixed tmp issue and no more tempdir in ballz
hostvarize world readable and admin users
always set shell tempdir
added comment to discourage use of exception/flow control
* Mostly revert expand_user as it's not quite working.
This was an additional feature anyhow.
Kept the use of pwd as a fallback but moved it to a second ssh
connection. This is not optimal but getting that to work in a single
ssh connection was part of the problem holding this up.
(cherry picked from commit 395b714120522f15e4c90a346f5e8e8d79213aca)
* fixed script and other action plugins
ensure tmpdir deletion
allow for connections that don't support new options (legacy, 3rd party)
fixed tests
* Add validation for the next to last line of a module
* Fix last error code
* Reduce to a single conditional
* Fix conditionals
* Move the final warnings statement to main() in mysql_replication
* Update validate-modules arg_spec introspection to be faster, by only mocking the imports we explicitly list
* The use of types.MethodType in redhat_subscription wasn't py3 compatible, use partial instead
* Remove argument_spec import hacks, make them errors, we can ignore them with ansible-test
* Enable the --arg-spec flag for validate-modules
* Mellanox OS name change: MLNXOS changed to ONYX
Signed-off-by: Samer Deeb <samerd@mellanox.com>
* Fix alphabetical order of modules metadata
Signed-off-by: Samer Deeb <samerd@mellanox.com>
* Resolve newly added tests as filters
* Add code smell to test for ansible provided jinja tests as filters syntax
* Add docs for no-tests-as-filters code smell test
* Address tests as filters in new integration tests
* Address feedback
* Address feedback 2
* Update validation test for new copyright
Ensure new modules without the new copyright header fail
validation
Ensure existing modules without copyright in top 20 lines fail
* Add documentation of 108 error
Create label in developing modules documentation so that
the validation page can point to it
* Ensure new style copyright header passes test!
* windows dev docs - vagrant info
* added info about FileUtil and LinkUtil
* Initial edit pass - WIP
* updated some wording
* fix some more general sayings to be more professional
* Add docs describing some additional behaviors around modules, to outline why generic modules will not be accepted
* Add/copy the generic module guidelines to developing_modules
* Edits for clarity
* Edits for clarity
* Refactor common network shared and platform specific code into package (part-1)
As per proposal #76 refactor common network shared and platform specific
code into sub-package.
https://github.com/ansible/proposals/issues/76
* ansible.module_utils.network.common - command shared functions
* ansible.module_utils.network.{{ platform }} - where platform is platform specific shared functions
* Fix review comments
* Fix review comments
Empty __init__ will allow us to use python namespaces with all of these
files. That may be something we want to take advantage of for allowign
them to be expanded by user dirs. Also might be needed for AnsiballZ or
other wrapper enhancements in the future.
* Warn on tests used as filters
* Update docs, add aliases for tests that fit more gramatically with test syntax
* Fix rst formatting
* Add successful filter, alias of success
* Remove renamed_deprecation, it was overkill
* Make directory alias for is_dir
* Update tests to use proper jinja test syntax
* Update additional documentation, living outside of YAML files, to reflect proper jinja test syntax
* Add conversion script, porting guide updates, and changelog updates
* Update newly added uses of tests as filters
* No underscore variable
* Convert recent tests as filter changes to win_stat
* Fix some changes related to rebasing a few integration tests
* Make tests_as_filters_warning explicitly accept the name of the test, instead of inferring the name
* Add test for tests_as_filters_warning
* Update tests as filters in newly added/modified tests
* Address recent changes to several integration tests
* Address recent changes in cs_vpc
* dev_guide: highlight Python code snippets
* dev_guide: use monospace for inline source code
* dev_guide: use links for classes and methods
Methods and classes prefixed with :method: and :class: will become
links once we have documentation for the relevant classes and methods.
Thanks to Toshio for pointing that.
* Remove uses of assert in production code
* Fix assertion
* Add code smell test for assertions, currently limited to lib/ansible
* Fix assertion
* Add docs for no-assert
* Remove new assert from enos
* Fix assert in module_utils.connection
* Protect AWS credentials from accidental commits
* Improve documentation for IAM policies
* Update ELB tests to be multi region
Allow AZs to reflect the region in which the tests are run.
This will not work for regions with fewer than three AZs,
but those are relatively rare
* Add openssh-client to default docker container.
* Include Azure requirements in default container.
To do so, handling of pip requirements was updated to install each
set of requirements separately and then run a verification pass to
make sure there are no conflicts between requirements.
* Add missing --docker-no-pull option.
* Add documentation for the azure-requirements test.
* new documentation for unit testing - especially module unit testing
* unit test documentation reformatting and further fixes
* unit test documentation - point to online coverage reports & fix bad spaces
* Small copy edits.
* First pass copy edit / rewrite. More info needed.
* testing documentation - clean up structure, especially code coverage - reduce repetition
* module unit test documentation - improved introduction
* testing documentation - more fixes from and inspired by review from dharmabumstead
* testing documentation - fixes from mattclay + some other minor tweaks
* More copy edits.
* testing documentation - further fixes from review
* Copy edits
* Copy edits
* More copy edits.
* updated docs
- for devs:
- added inventory/vars section
- made some updates to general section and other plugin types
- for users:
- added 'user' plugin section to start describing the plugins
- docs on types, what they are and how to use
- removed ref to deleted AUTHORS file
- corrected several typos/headers
- added descriptions to config.rst template
- ignore generated files for cli/plugins and config
- remove new generated files on `make clean`
- moved details from devguid and intro doc to plugin specific pages
- pretied up lookup notes
- changed precedence ref to not conflict config
- removed duplicate config data, as config is autogenerated and up to date
- put new plugins under playbooks
- added `pass` cause rst/python dislikes fractions
- removed dupe in .gitignore, alpha sorted to avoid moar dupes
- added try cause rst/python freaks out
* generate plugins into their own dir
only do plugins that support docs
use toctree from main plugins page
As discussed before we selected win_environment to the documentation,
and point to win_uri for a more advanced module.
If we want to make this the reference module, we have to get this one
absolutely right in every possible way.
This PR cleans up both win_environment and win_uri, and makes the
required changes to the windows module development section.
* Consistency and document treatment of default bool values
* Document that default bool values can be any Ansible recognized bool.
choose the one that reads better in context
* For fragments used by the copy module, make bool types use type=bool and not choices
* Edit for clarity
* Fix refs for local_facts and various cli :option:
* Fix dev_guide/testing_pep8 refs
* remove ref to non-existing 'developing_test_pr'
* Fix ref to ansible-vault encrypt_string
* Removed hard-to-localize colloquialism.
* Rename '_ansible-pull' in playbooks_intro.
It was conflicting with rst/ansible-pull.rst. Nothing
seems to reference it.
* Add explicit targets for and update refs
Replace some ':doc:' use with ':ref:'.
Replace some :ref: to section names with explicit targets
(:doc:`Dynamic vs. Static` -> :ref:`dynamic_vs_static` etc)
* The 'YAML+Jinja' syntax lex fails here, so just use yaml
Since the yaml+jinja highlight fails, code wasnt highlighted
at all, but 'yaml' works more or less.
* just use no lexer for the < python2.6 examples
py3 will fail highlighting them, and 'python2' throws
a lexer warning, and nothing actually highlights it, so
just disable.
from __future__ unicode_literals leads to developer confusion as
developers no longer can tell whether a bare literal string is a byte
string or a unicode string. Explicit marking as u"" or b"" is the way
to solve the same problem in the Ansbile codebase.
* 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
We are reserving the _ identifier for i18n work. Code should use the
identifier dummy for dummy variables instead.
This test is currently skipped as someone needs to generate the list of
files which are currently out of compliance before this can be turned
on.
* Implement ability to limit module documentation building:
- Added new option to plugin_formatter.py to support passing-in a list of
modules for which the documentation should be built.
- Updated docuemtnation Makefile to allow specifying list of modules via
environment variables (defaulting to all modules).
- Update instructions for building documentation and module development to
include commands and description of limiting module documentation builds.
* Updated implementation for limiting module documentation building:
- Pass list of modules (or None) to list_modules function instead of string.
- Move conversion of module list to argument parsing code.
- No special keywords. Default ("") means build all modules. For no modules just
specify non-existing module name.
- Updated documentation to reflect the changes.
* Updated implementation for limiting module documentation building:
- Use better default value, and don't treat "" as special case.
- Conditionally invoke different variants of command in Makefile instead of
using special value "".
* Minor edits
Wording tweak
* Create get_exception and wildcard import code-smell tests
* Add more detail to boilerplate and no-basestring descriptions
* Remove the no-list-cmp test as the pylint undefined-variable test covers it
* ManageIQ: manageiq_user module, module utils and doc_fragment
ManageIQ is an open source management platform for Hybrid IT.
This change is adding:
- manageiq_user module, responsible for user management in ManageIQ
- manageiq utils
- manageiq doc_fragment
* Handle import error
* Use formatting options
* group parameter is required
* changed doesn't need to be an attribute
* resource dictionary should contain values which isn't None
* move from monitoring to remote-management
* Use ManageIQ nameing convention
* Do not set defauts in arguments
* Use idempotent state parameter instead of action
* Check import error in the manageiq util class
* Update the miq documentation
* rename the connection configuration from miq to manageiq_connection
* All messeges start with non cap, fix typos, add examples, rename vars
* more typos fixes
* Make sure we insert only strings to logs by using % formating
* use suboptions keyword for the manageiq connection
* do not log the managiq connection struct (it include sensitive information like username and password)
* add missing from __future__
* ahh, wrong no-log line
* Use sub options
* Added initial developing module doc for Windows
* Added to dev index, made formatting changes and moved obsolete docs
* changes based on PR feedback
* some typos and extra information
* Minor updates
* minor wording clarifications
* remove references to "remote" Windows hosts
* update template/text to remove legacy `#WANT_JSON`/`#POWERSHELL_COMMON`
* use per-execution envvars for ANSIBLE_KEEP_REMOTE_FILES instead of stateful
* fix up minor sanity check issue
We do want to allow certain from __future__ imports in modules that make
it easier to code compatible python2 and python3. Note that
unicode_literals is specifically left out and should never be allowed.
Now that python-3.4+ allows u"" there's no good reason to use
unicode_literals.
Also switch tables in the validate_modules documentation to simple table format
This commit:
- Adds a table highlighting the status of each version and provides
a link to each major release's changelog
- Re-inforces how stable versions are maintained and for how long
- Moves this documentation out of the developer tree (this is
interesting for users too!) while keeping a link there.
* Adding ciscowlc_command module and unit tests.
* Adding __init__.py for unit test.
* Fixing PEP8 W503.
* Renaming module from ciscowlc_command to aire_command.
* Renaming aire_command to aireos_command.
* Add note on module development about the copyrights
This matches what's in CODING_GUIDELINES.md as of July 2017
* Add recommendation for standardizing on `Copyright (c) 2017 Ansible Project`
* s/with/should have/
* Fix more unicode
* Adding aruba_command module along with unit tests.
* Fixing PEP8 E303 too many blank lines.
* Adding default for timeout.
* Removing unused arguments. Moving default for timeout argument. Fixing cliconf to find hostname.
* Fixing PEP8 E302.
* All integration commands support --continue-on-error
* The network-integration command supports --inventory
* Add landing page for compile test docs.
* Add bot documentation links.
* WIP: Initial bulk move of quick start content into rst docs. Needs rewrite.
* Swapping out old quick start for new material (thanks @tstringer!). Still work in progress.
* Fixed formatting; removed extraneous file.
* Fixed some formatting errors.
* Once more, with feeling.
* Fixed formatting error
* Tell people to look for an existing module PR
There are a number of different ways to find existing PRs that add new
modules. Tell people about them to potentially avoid duplicates.
* Light edits
The note only had one colon instead of two, which allowed it to pass rstcheck but failed to actually generate the note in the HTML.
Also remove an unnecessary trailing colon.
* Initial commit for Pure Storage Ansible module
* Initial commit for Pure Storage Ansible module
* Initial commit for Pure Storage Ansible module
* Fix import issues as required by post-2.2
* Move last import to top
* Follow suggestions and only implement one module per PR
Fix documentation changes requested
* Documentation and formatting changes
* netscaler_service initial implementation
* Changes as requested by reviewers
* Skip some tests if under python2.6 and importing requests library
* Change option "operation" to "state"
* Remove print statements from netscaler module utils
* Catch all exceptions during login
* Fix fail message
* Add common option save_config
Initial commit to split includes into static imports/dynamic includes
This implements the new include/import syntax for Ansible 2.4:
* include_{tasks,role,variables} = dynamic
* import_{playbook,tasks,role} = static
The old bare `include` will be considered deprecated, as will any use of the `static: {yes|no}` option.
This also adds docs for import/include and reorganizing the "Playbook Reuse" section of the documentation.
* aws integration tests - provide an IAM policy that can be used for running them
* move documentation of aws policies into main integration testing documentation + some updates there
* Update testing_integration.rst
Edits
* 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
* Big testing doc refactor
* Combine all the testing documentation in to one place to make it easier to find
* Convert everything to RST
* Create testing_network guide
* Create testing landing page
* For each section detail "how to run" and "how to extend testing"
* More examples
* Lots more detail
This setting allows us to reference jinja2 and python stdlib docs
via docutils refs instead of hardcoding urls.
Fixes#18039
Remove extraneous sphinx config
The Python3 dev doc is more general than just modules
* Rename it to make that obvious.
* Move generally applicable Python3 information to the Controller section
* Add a Py3/Py2 section on formatting strings
* Fix code-blocks to highlight as python
* Enhance python3 support page
* Add Python3/Python2 compat note
* Update module_utils.six to latest
We've been held back on the version of six we could use on the module
side to 1.4.x because of python-2.4 compatibility. Now that our minimum
is Python-2.6, we can update to the latest version of six in
module_utils and get rid of the second copy in lib/ansible/compat.
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
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.
* WIP Partners guide for adding multiple modules
* WIP
* WIP
* WIP
* WIP
* WIP
* HACK
* Revert hack
* Brian's feedback
* Remove squash notes
* Minor tidyups
* Unit & Integration tests (& minor tweaks)
* Details about Unit tests
* As we are about to feature freeze on Ansible 2.3 remove the notes about Ansible 2.4 and py2.4.
* Module names should be in the singular
* Scot & Dylan's feedback
* 5 PRs at once. Remove FIXMEs
* Formatting
* How to use Git & GitHub
* directories are in category & topic
* Expectations of Module authors
* Better wording for module author's responsibilities
* How to document your module
* Remove blank lines
* note:: Versions should be strings
* requirements on the host that executes the module.
* option names & option values
* Feedback
* formatting
* Scott's final feedback
* Initial version of aos_ip_pool module
* Add examples for IP Pool
* Break down ip_pool into smaller function
* Refactor do_load_resource
* Add get_display_name_from_file
* Add ‘src’ as an option to load ip pool from JSON file
* Rename directory network/apstra to network/aos
* Remove exception handling temporary
* Remove all ‘Exception as XX’ to be python 2.4 compatible
* Replace ‘== False’ with ‘is False’ for PEP8 Test
* Update documentation to be Yaml compatible
* Lisg all method imported from module_utils.aos
* Refactor to align with collection.find() changes
* Update examples by @gundalow’s recommendations
* Update Documentation per @gundalow’s recommendations
* Change the license per @gundalow recommendation
* Add exception handling for get_aos_session
* Change Auth format and add check_aos_version() to check minimum version
* Add a check for minimum version
* Refactor ‘src’ into ‘content’ to allow more options
Remove get_display_name_from_file in aos.py
Add content_to_dict in aos.py
* Fix variable name in do_load_resource
* Add mention of aos.py in module_utilities doc
* Add try/except for import yaml
* Add try/Except around main block of code and function
* Refactor to auto detect content_format, update doc accordingly
* Change create_new_ip_pool inputs
* Remove unused import
* Remove in_use as it’s never used
* Fix doc format
* Add version number in requirement doc
* Revamping module development docs - work in progress
* Refurb of developing modules content continues.
* Developing modules refurb work continues
* Continued refurb of developing modules content. Work-in-progress.
* Ibid
* Dev guide content refurb continues - WIP
* Ibid.
* Removed reference to old extras module repo
* Tweaks
* Removed some non-intro material; added link to github module PRs.
* Incorporated review feedback from @gundalow and @tkuratomi; fixed some links; renamed '*contributing' to '*checklist'
* Deprecate ec2_vpc module
The deprecation of ec2_vpc module has been discussed for
2 years and is causing duplication of effort as changes
are implemented for ec2_vpc rather than for the newer
alternatives
* Improve module deprecation documentation
Update the developing modules documentation with the latest
instructions on how to deprecate a module.
* developing_modules.rst is now in dev_guide, sync changes and delete the old version
* Cleaner RST & formatted code
* Tidyup roadmaps
* Link to repomerge
* Pull in abadger's fixes From https://github.com/ansible/ansible/compare/docs-code-block-fixes?expand=1
* Clean docsite/rst (apart from ROADMAP
John R Barker