Commit graph

57 commits

Author SHA1 Message Date
Toshio Kuratomi
46b1a999c6
Collections docs generation backport (#70515)
* Build documentation for Ansible-2.10 (formerly known as ACD).

Builds plugin docs from collections whose source is on galaxy

The new command downloads collections from galaxy, then finds the
plugins inside of them to get the documentation for those plugins.

* Update the python syntax checks
  * docs builds can now require python 3.6+.

* Move plugin formatter code out to an external tool, antsibull-docs.
  Collection owners want to be able to extract docs for their own
  websites as well.
* The jinja2 filters, tests, and other support code have moved to antsibull
* Remove document_plugins as that has now been integrated into antsibull-docs

* Cleanup and bugfix to other build script code:
  * The Commands class needed to have its metaclass set for abstractmethod
    to work correctly
  * Fix lint issues in some command plugins

* Add the docs/docsite/rst/collections to .gitignore as
  everything in that directory will be generated so we don't want any of
  it saved in the git repository
* gitignore the build dir and remove edit docs link on module pages

* Add docs/rst/collections as a directory to remove on make clean
* Split the collections docs from the main docs

* remove version and edit on github
* remove version banner for just collections
* clarify examples need collection keyword defined

* Remove references to plugin documentation locations that no longer exist.
  * Perhaps the pages in plugins/*.rst should be deprecated
    altogether and their content moved?
  * If not, perhaps we want to rephrase and link into the collection
    documentation?
  * Or perhaps we want to link to the plugins which are present in
    collections/ansible/builtin?

* Remove PYTHONPATH from the build-ansible calls
  One of the design goals of the build-ansible.py script was for it to
  automatically set its library path to include the checkout of ansible
  and the library of code to implement itself.  Because it automatically
  includes the checkout of ansible, we don't need to set PYTHONPATH in
  the Makefile any longer.

* Create a command to only build ansible-base plugin docs
  * When building docs for devel, only build the ansible-base docs for
    now.  This is because antsibull needs support for building a "devel
    tree" of docs.  This can be changed once that is implemented
  * When building docs for the sanity tests, only build the ansible-base
    plugin docs for now.  Those are the docs which are in this repo so
    that seems appropriate for now.

* Docs: User guide overhaul, part 5 (#70307)

(cherry picked from commit db354c0300)

* Need to return any error code from running antsibull-docs (#70763)

This way we fail early if there's a problem

(cherry picked from commit 1e3989c9f7)

Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
2020-07-20 14:28:35 -07:00
Alicia Cozine
6fffb0607b WIP: Docs: User guide overhaul, part 4 (#69266)
Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
2020-05-15 16:18:07 -04:00
Sloane Hertel
34458f3569
Update inventory caching documentation (#69100) 2020-05-05 15:10:57 -05:00
Sandra McCann
8042d226e4
fix make webdocs warnings (#68411) 2020-03-25 13:13:56 -05:00
Alicia Cozine
69543b47c9 fix last 7 docs errors on post-migration test runs (#68115)
* address toc-tree-glob-pattern-no-match errors

* address Include-file-not-found error

* address 2.10 porting guide errors, add warning to page

* updates individual plugin type pages

* Add ignores.

Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
Co-authored-by: Matt Clay <matt@mystile.com>
2020-03-23 11:14:21 -05:00
Andrew Klychkov
ad8df69b58
docs/docsite/rst/: fix typos (#67645) 2020-02-21 10:57:07 +00:00
Ganesh Nalawade
1cfab26fab
Fix netconf plugin related to collections (#65718)
* Fix netconf plugin related to collections

Fixes #65655 (partly)

*  Make netconf plugins configurable so that the
   information of ncclient device handler
   for give platform resides in the platform
   specific netconf plugin.
*  If the device handler value in ncclient is
   different from the ansible_network_os value
   the right value of `ncclient_device_handler`
   should be set in the plugin documentation.

* Fix review comments

* Fix CI issue

* Fix review comment
2019-12-20 12:25:59 +05:30
Sandra McCann
7084dd727a clarify httpapi with an example (#65083) 2019-11-25 16:30:16 -06:00
Sloane Hertel
c1f280ba6e
Inventory CLI - Ignore settings for when vars plugins should run (#65073)
* Inventory CLI - Ignore settings for when vars plugins should run and just always run them

* Add note to porting guide

* Fix loading vars plugins

* changelog

* Remove a staging test for ansible-inventory since it ignores that setting
2019-11-25 13:16:03 -05:00
Sloane Hertel
a4b36b2e6a Update cache plugin documentation (#63635)
* Update cache plugin documentation since all cache plugins shipped with Ansible can be used for caching inventory since 2.8

* Update docs/docsite/rst/plugins/cache.rst

Co-Authored-By: Abhijeet Kasurde <akasurde@redhat.com>

Co-Authored-By: John R Barker <john@johnrbarker.com>
2019-11-18 16:00:26 -06:00
Sloane Hertel
c1f1b2029c
Support vars plugins in collections (#61078)
* Move var plugins handling to a separate file

* Allow var plugins to require whitelisting

* Add global configuration ('demand', 'start') for users to control when they execute

* Add 'stage' configuration ('all', 'task', 'inventory') for users to control on a per-plugin basis when they execute

* Update ansible-inventory and InventoryManager to the global and stage configuration

* Update host_group_vars to use stage configuration and whitelisting

* Add documentation for using new options and to the developer's guide

* Add integration tests to exercise whitelisting and the new configuration options, using vars plugins in collections, and maintain backward compatibility

* Changelog

Co-Authored-By: Brian Coca <brian.coca+git@gmail.com>
Co-Authored-By: Sandra McCann <samccann@redhat.com>
2019-11-04 11:41:14 -05:00
Sloane Hertel
d41050b28b Add some documentation about plugins in collections (#62465)
* Add some documentation about using plugins in collections

- FQCN requirements
- Sharing code in collections
- Limitations with inventory caching
2019-09-26 12:00:26 -04:00
Martin Klapproth
dc7a765e57 fix fact caching plugin name from json to jsonfile (#62198) 2019-09-12 15:45:43 -04:00
Alicia Cozine
44b6f2ff56 removes last :doc: links in other sections of the docs (#58432)
* removes last :doc: links in other sections of the docs

* fix references to playbooks intro page
2019-06-27 12:18:17 -04:00
Sandra McCann
cca365061c
add how to create HttpApi plugins for network modules (#54340)
* initial port over from gdoc

* crosslink httpapi pages

* Add some examples?

* Add quick example of using Connection

* Fix indentation of python code blocks

* moved to a full developer guide for networks

* Try to clarify some examples

* Fix typos

How did I even do that?
2019-04-22 13:21:21 -04:00
Jiri Tyr
7efb952825 Adding missing comma (#55254) 2019-04-15 15:02:26 -05:00
Sebastian Gumprich
7239218773 Update inventory.rst (#53656) 2019-03-21 11:28:50 -05:00
Sloane Hertel
9687879840
Fix inventory cache interface (#50446)
* Replace InventoryFileCacheModule with a better developer-interface

Use new interface for inventory plugins with backwards compatibility

Auto-update the backing cache-plugin if the cache has changed after parsing the inventory plugin

* Update CacheModules to use the config system and add a deprecation warning if they are being imported directly rather than using cache_loader

* Fix foreman inventory caching

* Add tests

* Add integration test to check that fact caching works normally with cache plugins using ansible.constants and inventory caching provides a helpful error for non-compatible cache plugins

* Add some developer documentation for inventory and cache plugins

* Add user documentation for inventory caching

* Add deprecation docs

* Apply suggestions from docs review

* Add changelog
2019-03-06 12:12:35 -06:00
Yanis Guenane
fcec3d0600 Become plugin: Update documentation to match other plugin doc (#53266) 2019-03-04 07:13:52 -06:00
Pilou
d8a2d64ec1 osx_say callback plugin: add espeak support, rename to say (#33740)
* rename into say

* add support for espeak command

* adds symlink from osx_say to say

* Update version number
2019-02-26 09:46:35 -06:00
Matt Martz
445ff39f94
Become plugins (#50991)
* [WIP] become plugins

Move from hardcoded method to plugins for ease of use, expansion and overrides
  - load into connection as it is going to be the main consumer
  - play_context will also use to keep backwards compat API
  - ensure shell is used to construct commands when needed
  - migrate settings remove from base config in favor of plugin specific configs
  - cleanup ansible-doc
  - add become plugin docs
  - remove deprecated sudo/su code and keywords
  - adjust become options for cli
  - set plugin options from context
  - ensure config defs are avaialbe before instance
  - refactored getting the shell plugin, fixed tests
     - changed into regex as they were string matching, which does not work with random string generation
     - explicitly set flags for play context tests
 - moved plugin loading up front
 - now loads for basedir also
 - allow pyc/o for non m modules
 - fixes to tests and some plugins
 - migrate to play objects fro play_context
 - simiplify gathering
 -  added utf8 headers
 - moved option setting
 - add fail msg to dzdo
 - use tuple for multiple options on fail/missing
 - fix relative plugin paths
 - shift from play context to play
 - all tasks already inherit this from play directly
 - remove obsolete 'set play'
 - correct environment handling
 - add wrap_exe option to pfexec
 - fix runas to noop
 - fixed setting play context
 - added password configs
 - removed required false
 - remove from doc building till they are ready

future development:
  - deal with 'enable' and 'runas' which are not 'command wrappers' but 'state flags' and currently hardcoded in diff subsystems

* cleanup

  remove callers to removed func
  removed --sudo cli doc refs
  remove runas become_exe
  ensure keyerorr on plugin
  also fix backwards compat, missing method is attributeerror, not ansible error
  get remote_user consistently
  ignore missing system_tmpdirs on plugin load
  correct config precedence
  add deprecation
  fix networking imports
  backwards compat for plugins using BECOME_METHODS

* Port become_plugins to context.CLIARGS

This is a work in progress:
* Stop passing options around everywhere as we can use context.CLIARGS
  instead

* Refactor make_become_commands as asked for by alikins

* Typo in comment fix

* Stop loading values from the cli in more than one place

Both play and play_context were saving default values from the cli
arguments directly.  This changes things so that the default values are
loaded into the play and then play_context takes them from there.

* Rename BECOME_PLUGIN_PATH to DEFAULT_BECOME_PLUGIN_PATH

As alikins said, all other plugin paths are named
DEFAULT_plugintype_PLUGIN_PATH.  If we're going to rename these, that
should be done all at one time rather than piecemeal.

* One to throw away

This is a set of hacks to get setting FieldAttribute defaults to command
line args to work.  It's not fully done yet.

After talking it over with sivel and jimi-c this should be done by
fixing FieldAttributeBase and _get_parent_attribute() calls to do the
right thing when there is a non-None default.

What we want to be able to do ideally is something like this:

class Base(FieldAttributeBase):
    _check_mode = FieldAttribute([..] default=lambda: context.CLIARGS['check'])

class Play(Base):
    # lambda so that we have a chance to parse the command line args
    # before we get here.  In the future we might be able to restructure
    # this so that the cli parsing code runs before these classes are
    # defined.

class Task(Base):
    pass

And still have a playbook like this function:

---
- hosts:
  tasks:
  - command: whoami
    check_mode: True

(The check_mode test that is added as a separate commit in this PR will
let you test variations on this case).

There's a few separate reasons that the code doesn't let us do this or
a non-ugly workaround for this as written right now.  The fix that
jimi-c, sivel, and I talked about may let us do this or it may still
require a workaround (but less ugly) (having one class that has the
FieldAttributes with default values and one class that inherits from
that but just overrides the FieldAttributes which now have defaults)

* Revert "One to throw away"

This reverts commit 23aa883cbed11429ef1be2a2d0ed18f83a3b8064.

* Set FieldAttr defaults directly from CLIARGS

* Remove dead code

* Move timeout directly to PlayContext, it's never needed on Play

* just for backwards compat, add a static version of BECOME_METHODS to constants

* Make the become attr on the connection public, since it's used outside of the connection

* Logic fix

* Nuke connection testing if it supports specific become methods

* Remove unused vars

* Address rebase issues

* Fix path encoding issue

* Remove unused import

* Various cleanups

* Restore network_cli check in _low_level_execute_command

* type improvements for cliargs_deferred_get and swap shallowcopy to default to False

* minor cleanups

* Allow the su plugin to work, since it doesn't define a prompt the same way

* Fix up ksu become plugin

* Only set prompt if build_become_command was called

* Add helper to assist connection plugins in knowing they need to wait for a prompt

* Fix tests and code expectations

* Doc updates

* Various additional minor cleanups

* Make doas functional

* Don't change connection signature, load become plugin from TaskExecutor

* Remove unused imports

* Add comment about setting the become plugin on the playcontext

* Fix up tests for recent changes

* Support 'Password:' natively for the doas plugin

* Make default prompts raw

* wording cleanups. ci_complete

* Remove unrelated changes

* Address spelling mistake

* Restore removed test, and udpate to use new functionality

* Add changelog fragment

* Don't hard fail in set_attributes_from_cli on missing CLI keys

* Remove unrelated change to loader

* Remove internal deprecated FieldAttributes now

* Emit deprecation warnings now
2019-02-11 11:27:44 -06:00
Nathaniel Case
7ad238b358
Document httpapi and cliconf plugins (#49503)
* Create new documentation pages for httpapi and cliconf

* Add new documentation to plugins toctree and Makefile

* Add DOCUMENTATION to cliconf

* Apply suggestions from code review
2019-02-08 11:04:05 -05:00
Felix Fontein
f6122fb63b Fix docs syntax highlighting errors (#50836)
* Add support for [WARNING]: ...

* Fix unreachable/failed output lexing.

* Detecting retry/--limit lines.

* Removing strange (invisible) characters which cause lexing problems.

* Using better-fitting lexers.

* Improve YAML lexing: don't accept quotes in keys.

* Add Django lexer (unchanged) from Pygments.

* Add support for != and % operators.
2019-01-24 16:09:41 -06:00
Pierre-Louis Bonicoli
7e278b23b4 inventory plugin order: update doc
add doc for #44428:
- add changelog fragment
- update porting guide
also:
- update auto inventory plugin doc
- mention toml plugin in examples
2018-12-12 09:35:13 -08:00
Pilou
1bad617f29 Inventory plugins move auto before ini (#44428)
* inventory plugins: try auto before ini

auto plugin should run before ini to avoid ini being able to parse
some plugin configuration YAML files successfully.

* Update comment

comment was added by 2ffe3c42bb but
related code was later removed by
506e6a0b2d.
2018-12-11 15:17:05 -05:00
Alicia Cozine
e700309618
Refine plugin docs (#49324)
* local TOCs, anchors, better headings, :ref:-not-:doc: links on all plugin pages
2018-11-29 14:03:00 -06:00
Brian Coca
7f04ee1eb4 corrected action plugin docs (#49321)
fixes #49277
2018-11-29 14:44:16 -05:00
Matt Martz
45ff6df1af Remove Deprecated configs 2.8 (#46825)
* Removed deprecated ANSIBLE_HOSTS

* Bump sudo/su configs to match deprecation version for cli and playbook args

* Bump include configs to match deprecation version for 'include'
2018-11-05 12:08:13 -05:00
Richard Metzler
acda7bae5f fix callback name
+label: docsite_pr
2018-10-19 18:17:49 -04:00
Sloane Hertel
43d12c11be Add 'auto' to documented default enabled inventory plugins (#46621)
* Correct default inventory plugins enabled in docs and example/ansible.cfg

* Fix headers
2018-10-08 14:07:46 -05:00
Sloane Hertel
c4d1f0d416 Add docs for inventory caching (#46402)
* Add docs for inventory caching

* Fix subsection headers

* Fix top header
2018-10-08 13:34:24 -04:00
Sandra McCann
df3655968f Infoblox scenario guide (#45664)
* creates infoblox scenario guide
* adds link to infoblox guide from modules
* adds WAPI to prerequisites
2018-09-24 14:25:01 -05:00
Sloane Hertel
33e9d67801
Add some inventory plugin documentation (#44727)
* Add some additional documentation about getting inventory plugins working using YAML inventory configuration files
2018-08-30 09:35:56 -04:00
Andreas Olsson
1a11cecaef Prefer https:// links in the docs site
All the changed urls are availible by way of https://. Most of them
already redirect.
2018-08-01 08:20:40 -07:00
Brian Coca
475abc0af7
inventory plugin docs (#42022)
* inventory plugin docs
* added set options
* minor wording and formatting fixes
* changed headers to std as per #35520, also added to main readme
* unified inventory plugin devel, referenced from generic plugin dev
* fixed typos and update as per feedback
2018-07-05 17:30:46 -04:00
Andrew Gaffney
21b99bff94
Fix 'ansible-doc' command in action plugin docs (#42206) 2018-07-02 13:26:46 -05:00
Troy Murray
15ce7c5bab change OS X to macOS (#41294)
* change OS X to macOS

<!--- Your description here -->

+label: docsite_pr

* Update all Mac OS X references to be macOS

* Drop extra Mac
2018-06-26 14:09:23 -04:00
Brian Coca
5cf1a5edfd corrected version added 2018-05-18 11:34:37 -04:00
Brian Coca
32c2aae258
document lookup errors optoin (#39645)
* document lookup errors optoin

* changed to doc

* updated as per feedback
2018-05-11 15:09:53 -04:00
Alicia Cozine
c8a9b411bc
Last docs link fixes (#39391)
* should not need <>, but fails without

* adds anchor to keywords page, uses it on plugins pages

* fixes envvar link errors

* harmonize file name and ref name as python_3

* removes undefined-lable from ignore list
2018-04-27 13:21:39 -05:00
Alicia Cozine
4b52a54e18 Reduce warnings (#39254)
* removes FAQ links; no entries exist for linked config settings

* fixes various anchors and links

* addresses abadger comments, thanks

* marks orphan pages, avoids TOC errors

* adds links for remote_tmp setting to FAQ
2018-04-25 11:18:52 -07:00
Matt Martz
476d1f818e
Documentation for query/q. Fixes #38275 (#38558) 2018-04-25 12:55:34 -05:00
Matt Clay
9e8889bb70
Fix more docs errors. (#39051)
* Fix remaining unknown-document docs errors.
* Fix last toc-tree-missing-document docs error.
2018-04-20 00:24:47 -07:00
Matt Clay
4fc5e89e83 Fix docs build warnings. 2018-04-19 17:54:56 -07:00
Alicia Cozine
64dcc7def0 Fixes more rST errors (#39042)
* removes include, avoids duplicate label rST warnings

* reduces literal_block errors on playbooks_filters

* addresses TOC errors

* ref error on modules page

* trying ref for list_of_database_modules
2018-04-19 17:02:48 -07:00
Alicia Cozine
408e29cbd2 Link fixes (#39038)
* fixes links on plugins pages

* fixes links in community pages

* fixes links in user guide

* adds anchors on playbooks pages
2018-04-19 17:02:30 -07:00
scottb
c97e508806
[WIP] disambiguating autogenerated module docs attempted fix of #38439. (#38890)
Disambiguates autogenerated module docs - fixes #38439.
2018-04-17 18:45:07 -07:00
Brian Coca
bdbb89378f
centralize doc/config plugin lists (#38775)
* centralize doc/config plugin lists

also update list for generation in docsite
added note to ensure they are in sync

* updated shell page to list plugins

added some more docs hinting at plugins being configurable

* fix edit link for plugins
2018-04-16 09:29:49 -04:00
Abhijeet Kasurde
71e85a45c1 Add missing single quote in inventory_plugin doc (#37403)
Added missing single quote in inventory_plugin doc.

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
2018-03-15 01:23:34 -07:00
scottb
381359a8f8
Doc build warning/broken link clean-a-palooza (#37382)
* Doc build warning/broken link clean-a-palooza, WIP commit 1.

* Fixed broken anchor

* Fixing additional broken links; converting from doc to ref.

* Fix anchor
2018-03-14 12:44:21 -07:00