Commit graph

448 commits

Author SHA1 Message Date
David Newswanger
3f5caf659e added support for --testcase flag in ansible-test (#36134)
* added support for --testcase flag in ansible-test

* fixed command format

* added tab completion

* fixed sanity issues

* added documenation for --testcase

* don't autocomplete when multiple modules are selected
2018-02-14 15:40:35 -08:00
scottb
373b1dcf59
Core Docs Refactor and Redesign (#36067)
* Docs refactor as outlined in https://github.com/ansible/proposals/issues/79. Moves content into 'guides'; refactors TOC; fixes CSS; design tweaks to layout and CSS; fixes generated plugin, CLI and module docs to fix links accodingly; more.

* Adding extra blank line for shippable
2018-02-13 07:23:55 -08:00
Rvgate
d5ae63c0ea Change wording of Going Further section (#35949)
* Change wording of Going Further section

The original wording was confusing with its non-devel branch part.
Made it much clearer for people to understand what to do.

Also removed the git command for creating branches, I believe a
develop should be aware of how basic git commands work.

* Edited for concision and clarity.

* Typo fix

* Typo fix
2018-02-11 00:32:22 -08:00
John R Barker
c3523cdd60
Test against a single transport (#35903)
Network integration tests can use tags to run only a specific transport
2018-02-09 16:07:41 +00:00
Joshua Smith
0c012703c1 Update developing inventory script docs. (#35639)
* Update developing inventory script docs.

* Copy edit.
2018-02-02 02:03:17 -08:00
Alicia Cozine
adf76b7d3f
Reflect new process for network integration tests (#35577)
With `ansible-test network-integration` we don't need the top level yaml files
except NXOS and Dell (for now)
2018-01-31 14:56:28 -06: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
Jordan Borean
4da19f2d6b Added code-smell check to verify filenames are allowed with Windows (#35436) 2018-01-29 13:46:02 -08:00
Matt Clay
7abdab6c9e Convert ansible-test compile into a sanity test. 2018-01-25 09:45:36 -08:00
Matt Clay
e0010f15e4 Add pslint sanity test. (#35303)
* Add pslint sanity test.

* Fix `no-smart-quotes` sanity test.

* Add docs for `pslint` sanity test.
2018-01-24 17:22:14 -08:00
Matt Martz
3c400c5899
ANSIBLE_METADATA doesn't support YAML currently, change 315 to invalid data type (#35009) 2018-01-17 14:15:22 -06:00
Matt Martz
a352d43824
Compare arg+aliases between docs and argument_spec (#34809)
* 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
2018-01-17 10:11:30 -06:00
Alexander Lex
59042d79f5 Update developing_api.rst to use correct inventory format for single explicit host (#34919)
Fix for #34918
2018-01-16 09:57:11 -06:00
Brian Coca
bbd6b8bb42 Temporary (#31677)
* 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
2018-01-15 21:15:04 -08:00
jctanner
b10d5f34ea Extend validate-modules to check the next to last line (#34819)
* 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
2018-01-15 15:49:35 +00:00
Matt Martz
dcc05093db Validate modules arg spec fixes (#34477)
* 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
2018-01-11 15:41:53 -08:00
Samer Deeb
f8884f12bc Mellanox OS name change: MLNXOS changed to ONYX (#34753)
* 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>
2018-01-11 22:21:17 +00:00
Pilou
b66863abf0 dev_guide: don't ask to use '© Ansible Project' (#34704)
contributor don't sign any copyright assignment, then this makes no
sense.
2018-01-11 14:23:36 +10:00
osLEccse
9c7d987395 Update developing_api.rst (#34629)
Module path needs to be array instead of a string variable in order to work.
2018-01-09 11:23:01 +00:00
Lars Kellogg-Stedman
29fbf0c756 remove erroneous '.' in docsite footer (#34592)
This removes an erroneous '.' in the docsite that someone pointed out
on irc.
2018-01-08 22:36:47 -08:00
Pilou
6a6f5129a9 dev_guide: fix a slip (#34143)
replace 'Formatting options' with 'Formatting functions'
2017-12-26 10:18:09 +00:00
Matt Martz
57575d1cfa
Fix tests as filters #4 (#33930)
* 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
2017-12-21 13:42:53 -06:00
John R Barker
c50da48049
Fix various RST warnings (#34084)
* Fix various RST warnings

* shorter lines
2017-12-20 15:20:05 +00:00
Will Thames
5f29cd5e60 Add validation test for new copyright (#32919)
* 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!
2017-12-16 09:23:54 -08:00
Jordan Borean
07e9df11b3
windows dev docs - vagrant info (#33515)
* 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
2017-12-12 08:16:22 +10:00
Matt Martz
2d2f288e77
Add docs describing some additional behaviors around modules (#33631)
* 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
2017-12-07 15:31:26 -05:00
Matt Clay
90ac38bd4c Fix module validator handling of empty options. 2017-12-05 16:46:05 -08:00
Ganesh Nalawade
11c9ad23d5
Refactor common network shared and platform utils code into package (#33452)
* 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
2017-12-03 21:42:30 +05:30
Toshio Kuratomi
7bd0af15d2
Enhance empty __init__ code-smell to check module_utils (#33438)
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.
2017-11-30 15:47:38 -08:00
Eike Frost
16081d2751 Add keycloak_client module for administration of Keycloak clients (#31716)
Allows administration of Keycloak (http://www.keycloak.org/) clients via the Keycloak REST API
2017-11-29 16:44:35 -05:00
Matt Martz
4fe08441be Deprecate tests used as filters (#32361)
* 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
2017-11-27 17:58:08 -05:00
Samer Deeb
cbf28c20cb Add Support for Mellanox switches: first module: mlnxos_command (#33121)
* Add Support for Mellanox switches: first module: mlnxos_command

Signed-off-by: Samer Deeb <samerd@mellanox.com>

* Add cliconf support for mlnxos

Signed-off-by: Samer Deeb <samerd@mellanox.com>

* 1- Fix short description, 2- remove waitfor

Signed-off-by: Samer Deeb <samerd@mellanox.com>

* remove usage of check_args

Signed-off-by: Samer Deeb <samerd@mellanox.com>
2017-11-27 20:55:08 +00:00
gaellick
bb38e34fc5 add prequisites for ubuntu dev env (#30713) 2017-11-27 14:58:13 -05:00
Pilou
16bcb0393e dev_guide: format code in testing_units_modules.rst (#33009)
* 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.
2017-11-27 14:41:53 -05:00
Sebastian Safari
a05bbb8a1b Update location of facts.py on module dev documentation (#32209)
* Update location of facts.py

I spent some time trying to find out where it was, since it's a 404 on a google search.

* Edits
2017-11-22 15:26:27 -08:00
Matt Martz
99d4f5bab4 Remove uses of assert in production code (#32079)
* 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
2017-11-13 11:51:18 -05:00
Will Thames
316e7939d6 [cloud] Improve aws testing and use {{ region }} var (#26892)
* 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
2017-11-09 11:56:31 -05:00
cnasten
f1fe467c22 nso_config module for setting configuration in Cisco NSO (#30973) 2017-11-09 13:34:41 +00:00
Jordan Borean
d43985aa46
windows development: info about module_utils and requires (#32060)
* windows development: info about module_utils and requires

* Edits.

* update for CI fix

* removed link to Python module utils
2017-11-02 07:15:25 +10:00
Aaron Huslage
01af68911f Change 'connection' to 'inventory' in description
Fixing a copy/paste typo.
2017-10-25 16:25:19 -04:00
Matt Clay
36b13e3e3d Fix ansible-test default image. (#31966)
* 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.
2017-10-20 08:48:01 -07:00
mikedlr
fbbffbabde Mdd module unit test docs (#31373)
* 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.
2017-10-19 13:36:57 -07:00
Toshio Kuratomi
c81314dcb9 Add a hack to test whether type=path should be used in a module 2017-10-09 21:15:56 -07:00
Michihito Shigemura
a71ca66e6e Fix typo in dev_guide/testing 2017-10-02 16:11:08 -04:00
Michihito Shigemura
78fd326908 Fix typo in dev_guide/developing_program_flow_modules 2017-10-02 16:10:45 -04:00
Michihito Shigemura
d0d1c7d249 Fix typo in dev_guide/developing_plugins (#31142) 2017-10-01 02:00:38 -07:00
Michihito Shigemura
221c01ff49 Fix typo in dev_guide/developing_modules_general (#31122) 2017-10-01 01:39:02 -07:00
Michihito Shigemura
b7b8c669a3 Fix typo in dev_guide/developing_modules_documenting (#31120) 2017-09-30 17:19:09 -07:00
Dag Wieers
e63d949951 Add a blank line, and use the Copyright format as used during rewrite
So there is a discrepancy between the dev guide and what has been changed on disk by toshio.
Not a big deal, but needlessly confusing.
2017-09-27 20:44:22 +02:00
Michihito Shigemura
b3cee37dc1 Update links in style_guide/trademarks (#30809) 2017-09-27 01:29:56 -07:00
Matt Martz
d40eff720c Update API example for 2.4 2017-09-26 14:39:36 -04:00
scottb
6c732bb670 Plugin doc update edits for #30490 (#30889)
* Edit pass 1 for #30490 - command line tools and developing plugins.

* Continuing edit pass for #30490. WIP

* Last round of copy edits for #30490.
2017-09-25 15:37:33 -07:00
Michihito Shigemura
b3177383da Fix typo in docs spelling_word_choice (#30785)
shocked that someone else spells the correst way, like me
2017-09-25 11:09:18 -04:00
Michihito Shigemura
303d622dcb Refactor doc resources in style_guide (#30794)
- Change links from http to https
- Correct or remove dead links
2017-09-23 09:13:17 +00:00
Brian Coca
b233f3f296 updated plugin docs (#30490)
* 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
2017-09-22 23:19:50 -04:00
Michihito Shigemura
b5546328dc Fix typo in docs grammar_punctuation (#30718) 2017-09-22 10:18:26 +00:00
Dag Wieers
31e7d735a3 win_environment: Make this the Windows reference module
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.
2017-09-21 03:20:17 +02:00
Monty Taylor
700a032bf1 Add an example of complex return argument (#28610) 2017-09-20 15:51:45 +01:00
Toshio Kuratomi
c82cf791dd Add a code-smell test for smart quotes and remove smart quotes from all files 2017-09-18 16:49:16 -07:00
Toshio Kuratomi
8a2f069468 Document boolean default value treatment (#30062)
* 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
2017-09-14 13:27:16 -07:00
Adrian Likins
dfc0084f01 rename dev..general_OLD.rst to ._rst (#30291)
So we don't try to build the rst, since it causes
lots of warnings to be shown and doesn't render correctly.
2017-09-14 11:23:36 -04:00
Adrian Likins
9cc63326b1 Misc docsite fixes (#30290)
* 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.
2017-09-14 11:17:56 -04:00
Matt Clay
df941df01d Remove references to obsolete PR Mover. (#30298) 2017-09-13 20:43:19 +00:00
Toshio Kuratomi
ff13d58c14 Remove use of unicode_literals as it is an anti-pattern
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.
2017-09-11 13:33:51 -07:00
Pilou
d67d202227 Fix typo: s/certfied/certified/ (#28951) 2017-09-02 13:46:46 -07:00
Adrian Likins
933298505a Update places we mention env vars to use :envvar: (#28887) 2017-09-01 14:52:18 -07:00
Dag Wieers
ccb6b39f45 Corrected RETURNS -> RETURN 2017-08-28 10:09:21 +02:00
Matt Clay
871bd24358 Fix documentation references. 2017-08-22 17:09:28 -04:00
Sam Doran
b7aa38c0d8 Minor fixes to Developer Docs (#28302)
* Grammar and formatting corrections

Indent JSON code example.
Double backticks for inline code examples.

* Remove trailing spaces

* CI fixes
2017-08-16 17:56:53 -07:00
Matt Clay
b52aeeabfa Roadmap updates and docs fix. (#28287)
* Update on 2.4 roadmap progress.
* Fix docs syntax for Python 2.
2017-08-16 10:55:19 -07: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
Prasad Katti
2c85ca3729 Formatting changes (#28133) 2017-08-14 02:09:19 +02:00
Stefan Midjich
6e4c0143b4 Typo in module example code (#28064)
In the DOCUMENTATION constant there is a typo on line 85 of this rst file.
2017-08-11 23:35:14 +02:00
Jordan Borean
362f032449 Changed docs requires to new format (#27918) 2017-08-09 06:05:46 +10:00
Joseph Miguel
f88f4394c8 Update developing_api.rst (#25922)
* Update developing_api.rst

* Update developing_api.rst

Edited.
2017-08-07 14:40:29 -04:00
Toshio Kuratomi
44935a5db6 Add a (disabled) code-smell test for detecting _ variables
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.
2017-08-07 11:11:31 -07:00
Branko Majic
f78baa1300 Implement ability to limit module documentation building (#24576)
* 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
2017-08-04 13:10:36 -07:00
Toshio Kuratomi
f4d7b9a596 code-smell test changes
* 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
2017-08-03 13:15:12 -07:00
Yaacov Zamir
48922660fe New model manageiq manageiq user (#26641)
* 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
2017-08-03 10:49:47 -04:00
Jordan Borean
ad5fa60a2b Added initial developing module doc for Windows (#27308)
* 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
2017-08-01 08:02:56 +10:00
Toshio Kuratomi
3a2670e0fd Allow specific __future__ imports in modules
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
2017-07-27 15:37:26 -07:00
David Moreau-Simard
e2d874c744 Improve release and development cycle documentation
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.
2017-07-25 23:38:08 -07:00
Martin Krizek
9c50933a80 docs: fix community meetings link (#27264) 2017-07-25 09:23:01 -04:00
Sam Doran
dac519135d Change docs to reference BOTMETA.yml instead of MAINTAINERS.txt (#26912) 2017-07-21 17:51:02 -04:00
James Mighion
b8337ee9d3 New module aireos_command (#26769)
* 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.
2017-07-19 23:14:52 +05:30
Ryan Brown
beca565c79 [Docs] Add note on module development about the copyrights (#26812)
* 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
2017-07-19 06:58:52 -04:00
James Mighion
f682d9bf49 Adding aruba_command module along with unit tests. (#26625)
* 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.
2017-07-19 09:49:12 +05:30
Matt Clay
e63f69464f Add ansible-test options and docs. (#26823)
* All integration commands support --continue-on-error
* The network-integration command supports --inventory
* Add landing page for compile test docs.
* Add bot documentation links.
2017-07-14 16:52:11 -07:00
Matt Clay
789218c215 Initial ansible-test sanity docs. (#26775)
* Rename no-iterkeys test for consistency.

* Require docs for all ansible-test sanity tests.

* Initial ansible-test sanity docs.

* Fix capitalization of Python.

* Fix sanity code smell test false positives.

* Fix another code-smell false positive.
2017-07-14 14:24:45 +01:00
scottb
4f01a323a0 Replace 'simple module development' topic (#26267)
* 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
2017-07-13 19:06:01 -07:00
Pilou
4b3d6dfa8a Use pycodestyle instead of pep8 (#25947) 2017-07-13 11:46:31 -07:00
John R Barker
ed0aabe02d Tell people to look for an existing module PR (#26287)
* 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
2017-06-30 20:16:26 +01:00
Scott Butler
ed17d7a0a5 Editing to fix wording from PR #26161. 2017-06-28 23:12:52 -07:00
Sam Doran
6f73ab84c6 Correct note syntax so Docker on non-Linux note shows up (#26161)
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.
2017-06-28 10:06:56 +01:00
John R Barker
5551e87755 RETURNS can include version_added (#25810) 2017-06-16 20:17:38 +01:00
Simon Dodsley
937d7993cc Initial commit for Pure Storage Ansible module (#25386)
* 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
2017-06-16 11:28:50 +01:00
Matt Martz
89c3151167 Give example of empty _meta in dyanmic inventory (#24085) 2017-06-15 09:51:34 -05:00
Abhijeet Kasurde
b89cb95609 Fix spelling mistakes (comments only) (#25564)
Original Author : klemens <ka7@github.com>

Taking over previous PR as per
https://github.com/ansible/ansible/pull/23644#issuecomment-307334525

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
2017-06-12 07:55:19 +01:00
John R Barker
4e6fee212a Correct link to plugins (#25530) 2017-06-09 13:06:08 +01:00
Pilou
bf0d0274cf doc: PEP 8 compliance is required (#25524) 2017-06-09 12:20:56 +01:00
George Nikolopoulos
a00089c341 New module: manage Citrix Netscaler service configuration (network/netscaler/netscaler_service) (#25129)
* 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
2017-06-08 08:33:32 -06:00
James Cammarata
483df9c5f8 Imports and includes (#25399)
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.
2017-06-06 16:39:48 -05:00
Michael De La Rue
e9e661ebbb aws integration tests - provide an IAM policy for running (#24725)
* 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
2017-05-19 14:37:39 -07:00
John R Barker
c9e05956b7 Update testing_units.rst (#24772) 2017-05-18 10:26:45 +01:00
Matt Clay
9178e176b5 Limit sphinx version on python 2.6. (#24678)
* Limit sphinx version on python 2.6.
* Fix issues identified by rstcheck.
2017-05-17 01:00:15 +08:00
Abhijeet Kasurde
9f3a405706 Fix URLs in dev_guide documentation (#24533)
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
2017-05-15 13:23:46 +01:00
Dylan Silva
6f4f7011f1 Updates to docs for developers (#24034)
- Added items to index for TOC
- Changed some formatting on overview_architecture
- removed some out of date items from developing_modules_general
2017-05-08 09:08:55 -07:00
Matt Clay
cec2b960f8 Fixes for pep8 and rstcheck issues. 2017-05-05 10:47:05 +08:00
scottb
02057f481b Added style guide (#24310)
* Added style guide

* Fixed index
2017-05-04 13:25:13 -07: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
John R Barker
8733253a76 Minor testing docs improvements (#24103)
Fix a few formatting issues spotted post review.
Also reapply missing commit
2017-04-28 11:58:38 +01:00
John R Barker
ecbf8e933a Docs how to test (2nd) (#24094)
* 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
2017-04-28 09:08:26 +01:00
Toshio Kuratomi
4c7a2e2622 Enable intersphinx for python stdlib and jinja2
This setting allows us to reference jinja2 and python stdlib docs
via docutils refs instead of hardcoding urls.

Fixes #18039

Remove extraneous sphinx config
2017-04-25 12:26:40 -07:00
David Mahler
09b247dd34 Minor grammatical corrections and improvements (#23886) 2017-04-23 00:47:03 -07:00
Adam Johnson
f1c4b434cd Tidy example inventories in "Developing Dynamic Inventory Sources" (#18758)
Thanks @adamchainz!
2017-04-20 09:36:16 -07:00
Matt Clay
cb1f57d4e5 Add rstcheck to ansible-test and correct issues. (#23550)
* Add rstcheck to ansible-test.
* Fix rst code-block languages and syntax errors.
* Fix rst inline literals.
* Update python 2 code block to pass tests on py 3.
2017-04-13 10:28:52 -07:00
Toshio Kuratomi
3180b4757e The Python3 dev doc is more general than just modules (#22950)
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
2017-04-04 11:18:19 -07:00
Scott Butler
5591d639f5 Fixed broken link. 2017-03-31 11:17:53 -07:00
Toshio Kuratomi
2fff690caa Update module_utils.six to latest (#22855)
* 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.
2017-03-23 13:35:05 -07:00
Dag Wieers
c254618d4f Improve test docs a bit more 2017-03-20 16:54:34 -07:00
Toshio Kuratomi
8de05d3752 [WIP] Documentation: Ansible-2.4 no longer supports Python-2.4 and Python-2.5 (#22721)
* Documentation: Ansible-2.4 no longer supports Python-2.4 and Python-2.5
* Switched to bullet points to enhance readability.
2017-03-16 18:49:29 -07:00
Dylan Silva
9dae697997 Updates to docs for metadata. (#22667)
* Updates to docs for metadata.

* Update developing_modules_documenting.rst
2017-03-15 15:34:00 -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
Artem Zinenko
990aa73ed8 Fix bug in 'Building A Simple Module' doc (#22447) 2017-03-10 08:43:45 -05:00
John R Barker
3fa5c55182 Fix docs type (#22405)
Fix docs typo
2017-03-08 13:42:42 +00:00
John R Barker
3afb67e9b2 Fix Docs build issues (#22295)
* restore network docs fragments

* Fix RST errors

* code-block formatting
2017-03-05 11:41:29 +00:00
Toshio Kuratomi
9d85d81ed0 Make the metadata docs agree with what's currently implemented 2017-02-27 09:27:00 -05:00
John R Barker
fdd03916a3 Document ANSIBLE_METADATA (#21250)
* Document ANSIBLE_METADATA

* Formatting

* Reive feedback - WIP

* notes about Declarative

* fix headings

* Use field lists

* typo

* review feedback

* Imports

* typo

* Toshio's feedback
2017-02-24 20:31:58 +00:00
John R Barker
48c6dd2689 Point to cloud/amazon/GUIDELINES.md in main repo (#21780) 2017-02-22 15:31:06 +00:00
Robin Schneider
3700bcb6dd Use HTTPS instead of legacy HTTP for ansible.com (#16870)
Mechanical edit done by this "one-liner":

```Shell
git ls-files -z "$(git rev-parse --show-toplevel)" | xargs --null -I '{}' find '{}' -type f -print0 | xargs --null sed --in-place --regexp-extended 's#http://(www\.|galaxy\.|)ansible\.com#https://\1ansible.com#g;'
```

Related to: https://github.com/ansible/ansible/issues/16869
2017-02-15 16:09:33 -08:00
John R Barker
53ac312382 validate-modules --arg-spec (#21331)
* validate-modules --arg-spec

* Update developing_modules_documenting.rst

* Never mock out ansible or ansible.module_utils

* No more false positives
2017-02-15 08:09:08 +00:00
John R Barker
cd6792a058 Docs partner checklist (bulk modules) (#20794)
* 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
2017-02-10 14:02:24 -08:00
John R Barker
959637ff59 How to document your module (#21021)
* 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
2017-02-10 12:15:55 +00:00
Damien
b71a62283c New Module : aos_ip_pool as part of network/aos (#21044)
* 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
2017-02-09 22:22:56 +00:00
Jiri Tyr
5d9dd5934a Making the decoration more clear (#20931) 2017-02-07 11:07:41 +00:00
Scott Butler
a002dca42d Edited for grammar, punctuation and spelling 2017-01-31 12:44:23 -08:00
Albert Mikaelyan
b89f222028 Some better explanation to release cycle 2017-01-31 12:36:42 -05:00
Matt Clay
10d9318de7 PEP 8 indent cleanup. (#20800)
* PEP 8 E121 cleanup.

* PEP 8 E126 cleanup.

* PEP 8 E122 cleanup.
2017-01-29 07:28:53 +00:00
scottb
13fc909058 Refurbish developing modules content - stage 1 (#20673)
* 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'
2017-01-27 14:03:26 -08:00
Sumit Kumar
9283772e54 Add doc_fragment and module util for NetApp platforms (#19607)
* Add doc_fragment and module util for NetApp platforms

* Make requested changes

* Fix links and change formatting.

* Fix description sections.
2017-01-25 09:51:57 +00:00
Will Thames
75a7ebe900 Deprecate ec2_vpc module (#20344)
* 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.
2017-01-19 11:25:28 +00:00
Scott Butler
1c8b85a6f1 Added support statement for older releases. 2017-01-13 11:59:16 -08:00
Toshio Kuratomi
08d6990e67 Fix code-blocks to use correct syntax highlighting 2017-01-08 09:18:45 -08:00
John R Barker
7df31aaca1 Fix all RST errors for docs/docsite/rst (#20005)
* 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
2017-01-07 11:38:52 -08:00
Toshio Kuratomi
1be3ac36df Fix block highlighting
Found out that we change the default highlighting to yaml.
So explicitly mark python code blocks as such.
2017-01-06 12:37:51 -08:00
Rodolfo Carvalho
8f3c435b27 Fix path to test plugin examples 2017-01-06 11:41:15 -05:00
Brian Coca
57f8b791d6 consolidated docs
point to new doc locations
removed non existing dirs
2017-01-06 09:16:59 -05:00