Commit Graph

603 Commits (9a9ef01997557556e9a940f1f3f36b3bb3655398)

Author SHA1 Message Date
Felix Fontein a6cc508822
Update the module lifecycle document to also cover plugins and collections (#74413)
Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
4 years ago
Matt Clay 8bd599d048 Change Shippable refs in docs to Azure Pipelines. 4 years ago
Matt Clay a30c55f68a Remove deprecated `common.removed` module_util.
Tests have been updated to reflect its removal as well.
4 years ago
Mark Chappell c387b318a6
AWS: update reference to auto-retrying ResourceNotFound (#72314)
AWS Dev Guidelines: update reference to auto-retrying ResourceNotFound

Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
4 years ago
Bill Nottingham 34c9ed8a28
Product-related updates. (#74454) 4 years ago
Alicia Cozine 9d9b08bece
fix spacing to fix header, reorg contributing page (#74421)
Co-authored-by: John R Barker <john@johnrbarker.com>
4 years ago
Abhijeet Kasurde 8d499bbc83
Update Kubernetes collection name in docs (#74440) 4 years ago
Mark Chappell 63afb33d86
Use is_boto3_error_code in 'standard' example (#72313)
Use is_boto3_error_code in 'standard' example rather than e.response['Error']['Code'] (#72313)

Co-authored-by: Sloane Hertel <shertel@redhat.com>
4 years ago
Mark Chappell cf08c23b4f
Update AWS dev guides to use collections utils and fragments (#72312) 4 years ago
Alicia Cozine c90922ee36
Docs - Split Developing collections page, add info on optional module_utils (#74105)
*
4 years ago
schurzi 5e5bfa8116
remove deprecated ansible.module_utils._text from documentation (#73211)
According to comment in ansible.module_utils._text it is deprecated and
should not be used. This is now reflected in the documentation.
4 years ago
Alicia Cozine c66cff444c
documents the use of ansible.legacy (#73942) 4 years ago
Marketka 0bf9b7fdf8
Added prerequisites to install for CentOS (#73993)
* Added prerequisites to install for CentOS as well so CentOS users don't have to look for alternatives for each Ubuntu package.

Signed-off-by: mm667937 <marketa.muzikova@broadcom.com>


Signed-off-by: mm667937 <marketa.muzikova@broadcom.com>
4 years ago
Andrew Klychkov 46b02e125f
dev_guide/testing_integration: update image list (#74017) 4 years ago
Jim Speir 4780e10a2b
Adding jborean93/WindowsServer2019 in docs (#73950) 4 years ago
sgpinkus efe97aeb31
Update developing_inventory.rst (#73931)
* Update developing_inventory.rst

hashes/dictionaries in JSON (JavaScript Object Notation) are represented by what JSON calls "objects", so use that established terminology instead of "hash", "dictionary", or "hash/dictionary" etc.

* Update docs/docsite/rst/dev_guide/developing_inventory.rst

Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
4 years ago
Sloane Hertel 95dc8f2361
Add some dev documentation for constructed features (#73497) 4 years ago
Alicia Cozine 30c465c1a9
Promote publication (#72400)
Co-authored-by: Sandra McCann <samccann@redhat.com>
Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
Co-authored-by: Sandra McCann <samccann@redhat.com>
4 years ago
Alicia Cozine b57444af14
Rebased pr73824 (#73934)
Co-authored-by: Eugene <k.evgen61@gmail.com>
Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
4 years ago
bylerbk 1ac2858b5a
Update developing_modules_general.rst (#73805)
##### SUMMARY
<!--- Fixing a typo. There was a double "you" in the text. -->


##### ISSUE TYPE
- Docs Pull Request

+label: docsite_pr
4 years ago
Felix Fontein b2015c98e2
validate-modules: make sure that options that potentially contain secret data have no_log set (#73508)
* Catch more potential errors (and increase false-positive rate).
* Flag some false-positives in lib/ansible/modules/ with no_log=False.

Co-authored-by: John Barker <john@johnrbarker.com>
4 years ago
Felix Fontein 3cc693b92c
Import test: improve docs, add more tests (#73600) 4 years ago
Sebastian Haderecker 27baa8cd86
OpenStack guidelines: Replace with link (#73617)
Replace the guidelines page with a link to the current guidelines on opendev.org.
4 years ago
Felix Fontein 1f3a90270b
Import sanity test for plugins (#72497) 4 years ago
Lydie 4059b37ab1
Conscious language added to user guide, development guide, and Ansible community guide, (#73574)
* Added conscious language note to index pages of guides
4 years ago
Matt Clay 607af05d36 Fix syntax errors detected by rstcheck.
The errors occur when using sphinx >= 2.0.0.
4 years ago
Felix Fontein 76604397cb
Mention that C(...) should be used for inline code. (#73312) 4 years ago
Felix Fontein 73aa571305
Make sure to mention collection version for version_added as well. (#73270) 4 years ago
Felix Fontein 270385f949
Remove 'type: complex' from the example, and mention that it should be avoided. (#73171) 4 years ago
Jens Heinrich 8a202cae3e
Update developing_collections.rst (#73142)
Fix typo - FQCN not FCQN.
4 years ago
azrdev 6487a239c0
developing_inventory sample code: fix undefined var "results" if get_option(cache)=False (#72977)
if user_cache_setting == False, then the previous code didn't parse the inventory source
4 years ago
Alicia Cozine e5ccd18be4
Wording changes to docs (#70082) 4 years ago
Evgeni Golov 57c2cc7c77
correct the reST rendering of the R() note (#72896) 4 years ago
Andrew Klychkov 0a7fcd135c
Docsite: update "Migrating Ansible content to a different collection" info (#72710)
* add a reminder about ignore-*.txt entries, fix formatting, add symlink removal note
* Update docs/docsite/rst/dev_guide/developing_collections.rst

Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: David Moreau Simard <moi@dmsimard.com>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
4 years ago
Abhijeet Kasurde a57539f764
Update VMware module development (#72603)
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
4 years ago
Marco Lembo 1937dd5e9c
Update developing_plugins.rst (#72305)
##### SUMMARY
ansible_date_time returns utc time. datetime.utcnow() rather than datetime.now()

##### ISSUE TYPE
- Docs Pull Request

+label: docsite_pr
4 years ago
Matthew Davis ddad9930aa
Clarify collection paths in docs (#72510)
* Clarify collection paths in docs, fix rst syntax, rephrase docs about using collection from folder/local git

Co-authored-by: Felix Fontein <felix@fontein.de>
4 years ago
Felix Fontein da1c1e8bb8
Add info on how to contribute to **community**-maintained collections as well. (#72494) 4 years ago
Felix Fontein 01d207a3e3
Improve argument spec documentation (#72335)
* Link to argument spec documentation from 'Creating a module'.

* Use items instead of sub-headings.

* Update deprecation information.

* Document conditional requirements.

* Document supports_check_mode and add_file_common_args.

* Add deprecation examples.

* Re-add word.

* Improve title.

* Fix RST formatting, add conditional dependency section starter.
4 years ago
Nathan Scott c20329a0f6
Update migrating_roles.rst (#72260)
Fix a typo in the sample spec file Source0 line
4 years ago
Ronald Eddy Jr d18901dd4a
Update HTTP -> HTTPS (#72244)
Co-authored-by: Ronald Eddy Jr <ron@Ronalds-MacBook-Pro.local>
4 years ago
Jordan Borean caba47dd3f
Add support for GSSAPI/Kerberos to urls.py (#72113)
* Add support for GSSAPI/Kerberos to urls.py

* Test out changes with the latest test container

* Get remote hosts working

* Fix up httptester_krb5_password reader

* Fix tests for opensuse and macOS

* Hopefully last lot of testing changes

* Dont do CBT on macOS

* Fixes from review
4 years ago
Erik Zettel 2b79cd2c0f
Fix typos (#72072) 4 years ago
Felix Fontein a077bca5d5
ansible-test: improve version number validation, validate some semantic versioning properties (#71679)
* Validate removal versions.
* Validate that removal collection versions and version_added collection versions conform to semver spec.
* Validate removal version numbers in meta/runtime.yml.
* Stricter validation for isodates (f.ex. YYYY-M-D is not allowed).
* Improve error reporting.
* Validate removal collection versions.

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
4 years ago
Jorge Vallecillo 94522b7c10
Fix typos (#71970) 4 years ago
Gonéri Le Bouder c1005147e0 doc: add vmware_rest_guidelines
Add the development guidelines for the vmware_rest collection.
4 years ago
Abhijeet Kasurde 4f990e7615
dev_guide: Add Pygments Lexer examples (#71458)
* dev_guide: Add Pygments Lexer examples

Fixes: #51307

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

* adds ansible-output lexer, remmoves unsupported lexers

Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
4 years ago
Andrew Klychkov 2655fc0c23
Docsite: update Migrating Ansible content to a different collection (#71854)
Co-authored-by: Felix Fontein <felix@fontein.de>
4 years ago
Andrew Klychkov a80131a283
Docsite: misc fixes (#71697) 4 years ago
Sloane Hertel 7048542199
Fix passing the connection timeout to connection plugins (#71722)
* Fix passing the connection timeout to connection plugins
4 years ago
Amin Vakil 7a0e545700
Add how to run unit test link in testing_units_modules doc (#71523)
* Add how to run unit test link in testing_units_modules
* Fix sanity test
4 years ago
Guillaume Vincent 1a06587f3b
Fix typo in the documentation (#71701)
Fix typo in the documentation: casting instead of casing
4 years ago
Andrew Klychkov 73bed95ead
Docsite: add reference to Style guide (#71694) 4 years ago
esmersmith a34043c6be
Changed all_modules references to list_of_collections in the documentation (#71656) 4 years ago
Zois Pagoulatos 1ad0f666d5
Fix typo in documentation (#71652)
Fix typo on the page about unit testing modules,
4 years ago
Sandra McCann bbd4ec13f1
clarify that collection names use same requirements as namespaces (#71639) 4 years ago
Andrew Klychkov 7bfeed3e24
Docsite: replace Latin phrases to English (#71588)
Replace Latin phrases like "e.g." and "i.e." and "etc." with English phrases. 

* Update docs/docsite/rst/community/committer_guidelines.rst
* Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
* Update docs/docsite/rst/dev_guide/developing_program_flow_modules.rst
* Update docs/docsite/rst/dev_guide/module_lifecycle.rst
* Update docs/docsite/rst/user_guide/intro_inventory.rst
* Update docs/docsite/rst/user_guide/playbooks_loops.rst
* Update docs/docsite/rst/user_guide/playbooks_reuse.rst
* Update docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst
* Update docs/docsite/rst/dev_guide/testing.rst
* Update docs/docsite/rst/dev_guide/testing_integration.rst
* Update docs/docsite/rst/porting_guides/porting_guide_2.5.rst
* Update docs/docsite/rst/reference_appendices/faq.rst
4 years ago
Andrew Klychkov bfba0ffc45
Docsite: improve developing_modules_documenting.rst (#71590)
* Docsite: improve developing_modules_documenting.rst

* add necessary dots to returns descriptions
4 years ago
Andrew Klychkov cda5854099
Docsite: improve spelling_word_choice.rst (#71592) 4 years ago
Alicia Cozine 29b20bd1b1
DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) 4 years ago
Andrew Klychkov 56423b1648
testing_sanity.rst: add argument for running in docker (#71223) 4 years ago
Amin Vakil bc6461432e
Add --allow-disabled to sanity docs (#71524) 4 years ago
Sandra McCann addee0699e
quick update to changelog instructins (#71492) 4 years ago
Patrick Reader 2b7461eb52
fix broken links due to master -> main branch rename (#71426) 4 years ago
Andrew Klychkov 5498b0bb71
Documentation: improve dev_guide/testing_integration.rst (#71370) 4 years ago
Andrew Klychkov b82889eef5
Add note about integration tests for new modules to the dev guide (#71345) 4 years ago
Sandra McCann 74f88c56a5
quick fix to change main back to devel (#71342)
* quick fix to change main back to devel
* Update docs/docsite/rst/dev_guide/developing_collections.rst

Co-authored-by: Felix Fontein <felix@fontein.de>
4 years ago
Rick Elrod ea58d7c233
Make it so callback plugins can act on implicit/explicit meta tasks (#71009)
Change:
- Now sends meta tasks to the task start callback
- Lets callback plugins opt-in to receiving implicit tasks

Test Plan:
- New integration tests

Tickets:
- Indirectly fixes #71007 by allowing custom callbacks with this data

Signed-off-by: Rick Elrod <rick@elrod.me>
4 years ago
Abhijeet Kasurde 4f993922c8
Add documentation about info/facts module development (#71250)
Fixes: #40151

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
4 years ago
Andrew Klychkov 180507c62b
dev_guide: improve developing_collections.rst (#71332) 4 years ago
Abhijeet Kasurde 606604bb97
Add warning about copyright year change (#71251)
To simplify project administration and avoid any legal issues,
add a warning in the docs. This reflects - https://github.com/ansible/ansible/issues/45989#issuecomment-423635622 and fixes: #45989

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
4 years ago
Sayee ecd3b52ad7
Writing style updates to Developing dynamic inventory topic (#71245)
* modified the writing style

* incorporated peer feedback
4 years ago
Abhijeet Kasurde ecea018506
Fix 404 links (#71256)
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
4 years ago
Andrew Klychkov a496b89d6f
overview_architecture.rst: fix playbook example (#71303) 4 years ago
Andrew Klychkov 9296ee9329
developing_modules_in_groups.rst: add note about releasing (#71305) 4 years ago
Sayee 7195788ffe
updates per writing style (#70978)
* updated to follow IBM and Ansible style guides
* modified heading underlines
* incorporated peer review feedback
4 years ago
Toshio Kuratomi fb144c4414
Update ansible doc formats (#71070)
* Fix tty_ify bugs and refactor

* Move tty_ify() and supporting attributes to the DocCLI class as that's
  the only thing using it.
* Add unittest for the code.
* Fix a bug where the substitution macros can be detected when they are
  a part of another word.
* Add support for L(), R(), and HORIZONTALLINE which were added to the
  website docs many years ago.

* Update test/units/cli/test_doc.py

Co-authored-by: Matt Clay <matt@mystile.com>

Co-authored-by: Matt Clay <matt@mystile.com>
4 years ago
Sloane Hertel a9eb8b0488
Add some documentation for the format of meta/runtime.yml (#71035)
* Document the format of meta/runtime.yml

* Document multiple Ansible versions

Clarify difference between deprecation and tombstone fields

* add note
4 years ago
Rick Elrod 7f62a9d7b5
Make cache adjudicator's flush call plugin flush (#70987)
Change:
- Previously CachePluginAdjudicator#flush only removed entries from the
  cache backend that it knew about by using them earlier. Now it calls
  the underlying plugin's flush() method.

Test Plan:
- New unit tests

Tickets:
- Fixes #68770

Signed-off-by: Rick Elrod <rick@elrod.me>
4 years ago
EthanHur 0c855dc70b
Guide users to use ansible-runner (#71063)
Update the docs to guide users to use `ansible-runner` instead of using Python API directly. In many use cases, executing Ansible playbooks are sufficient. In those use cases, `ansible-runner` is easier and much stable to use comparing with Python API, but there is no mention of it.
4 years ago
Sandra McCann 58145dff9c
document how to migrate between collections (#70243)
* document how to migrate between collections
* Apply suggestions from code review

Co-authored-by: John R Barker <john@johnrbarker.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
4 years ago
Sam Doran 7f0c84ea15
Update module debugging docs (#70847)
- Combine remote and local debugging instructions.
- Update the example code to match current AnsiballZ structure and behavior
- Change reference name and update references
- Clarify how PYTHON path is modified
- Also add note about other remote debugging tools.

Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
4 years ago
Sandra McCann 748ba96610
How to use rst :ref: for modules in collections (#70567) 4 years ago
Felix Fontein 7e2cc7db12
validate-modules: fix version_added validation for top-level, fix error codes (#70869)
* Also validate top-level version_added.

* Fix error code.

* Produce same version_added validation error in schema than in code (and stop returning it twice).

* Return correct error codes for invalid version_added for options and return values.

* Add changelog.

* Fix forgotten closing braket.

* Accept 'historical' for some top-level version_added.
4 years ago
Sviatoslav Sydorenko 20bb915092
Refactor Python API examples and docs
PR #70446: it's a follow-up for #70445.

It includes a merge of `examples/scripts/uptime.py` and a similar
code snippet from `docs/docsite/rst/dev_guide/developing_api.rst`.

This patch also changes the docs RST file to include contents of
the example file instead of holding a copy of a similar code.
4 years ago
David Shrewsbury bf98f031f3
Sanitize URI module keys with no_log values (#70762)
* Add sanitize_keys() to module_utils.

* More robust tests

* Revert 69653 change

* Allow list or dict

* fix pep8

* Sanitize lists within dict values

* words

* First pass at uri module

* Fix insane sanity tests

* fix integration tests

* Add changelog

* Remove unit test introduced in 69653

* Add ignore_keys param

* Sanitize all-the-things

* Ignore '_ansible*' keys

* cleanup

* Use module.no_log_values

* Avoid deep recursion issues by using deferred removal structure.

* Nit cleanups

* Add doc blurb

* spelling

* ci_complete
4 years ago
Sayee 1733253297
Modification of 'Adding modules and plugins locally' topic (#70659)
* Remediated the topic to comply with IBM style guide and minimalism practices
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
4 years ago
Baptiste Mille-Mathias 92e16c2838
Few fixes for reference_appendices/faq.html (#70719)
* Format using `` instead of `, add line breaks for long lines, rephrase or remove useless text.
Move some text.

* Add clearer version of OpenSSh is affected by SCP bug

* Review some pages using ansible doc writing guide.
4 years ago
Stef B fb3db170cc
Make Sources, Plugins sections easier to read (#70652)
Re-wrote the Inventory Sources section and also the next section to have shorter, clearer sentences with a more active voice.
4 years ago
Alicia Cozine f1f782fc37
partial update of community docs to reflect collections transition (#70488) 4 years ago
Abhijeet Kasurde 375c6b4ae4
docs: update date format in removed_at_date (#70597)
removed_at_date requires YYYY-MM-DD format.

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
4 years ago
Abhijeet Kasurde 20209c508f
docs: update module development docs (#70594)
Update module development docs for flattened modules directory.

Fixes: #70261 (at least partially)

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
4 years ago
Mark Chappell e1ba7dc52a
Update AWS Integration test docmentation (#70454) 4 years ago
Baptiste Mille-Mathias bd1378405b
Small documentation fixes (#70480)
* Add type for options in the sample module shown in Developing Modules, as this is required to have the tests being
green
* Remove duplicated strings: the same sentence is in "Python tips" and "Module security", keeping the
latter.
4 years ago
Sviatoslav Sydorenko 8d97c8c222 Fix the internal Python API usage examples
Previous version initialized the `TaskQueueManager` after calling
`Play.load()` while advertising a way to inject a custom library
location path. This caused the tasks loader not to find any custom
modules because it was triggered before the path was actually added
to the module loader.

This patch changes the order of the operations to ensure that the
customized `context.CLIARGS` actually influences things.

Resolves https://github.com/ansible/ansible/issues/69758.
4 years ago
Michael Ritsema 82e5d03bdb
Suggest ansible ad-hoc command while developing module (#70308)
If a local module has no documentation, the doc command will fail without any hints of what is wrong. Add another way to confirm the presence of a local module.
* Update docs/docsite/rst/dev_guide/developing_locally.rst

Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
4 years ago
Sandra McCann 5a28b2b86c
Add steps for how to create changelog.rst for a collection (#70262)
* Update docs/docsite/rst/dev_guide/developing_collections.rst
* add steps to create changelogs, add sentence about not using the tool
* add note for rerunning the command

Co-authored-by: Felix Fontein <felix@fontein.de>
4 years ago
Sandra McCann 83f6e4850b
document FQCN for M() and :seealso: in DOCUMENTATION blocks (#70245)
* document FQCN for M() in DOCUMENTATION blocks

* add note about c
4 years ago
Abhijeet Kasurde da868d9d60
docs: Add note about ansible-doc (#70162)
ansible-doc can only parse Python modules, added a note about
this is developer guide; Fixes: #69109
4 years ago
Jill R 0ef75f65d9
Fix broken link in AWS Guide (#70153)
Point to collection rather than ansible/ansible for example.
4 years ago