* 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.
Generate rst docs for plugins
Based on rst generated for modules. But generated plugin
docs go into docs/docsite/rst/plugins/$PLUGIN_TYPE/plugin_name.rst
( docs/docsite/rst/plugins/connection/ssh.py for ex)
* move plugins docs to rst/*_plugins/ subdirs for namespace
* Only gen support pages for modules for now.
* Add generated plugin docs to gitignore* add list_*_plugins templates
* support MODULES/PLUGINS filters for make htmldocs
Add a 'PLUGINS=ssh' filter env var like MODULES to filter plugins to build docs for.
* fixup 'historical' version_added, skip plugins/loader.py
* Fix plugins_by_support ref link to new plugins/*/ location
* use :ref: for common_return_values, allow empty version_added
* warnings on missing doc info
* add a prefix to _random_choice
It was colliding with the target for random_choice plugin
Addtions to porting_guide_2.4
* deprecated notice for win_package return values
* Added vars plugins, config api, inventory plugins. These were mostly backwards compatible.
Added notes for users and devs to check out new features once i write the 'feature docs' I'll
come back and link to them from here
* Porting Guides for Ansible Versions
Improve the user facing documentation.
Tell people what changes they need to make
* More porting guides
* Link porting guides from TOC
* Link porting guides from CHANGELOG.md
* typo in link
* Review feedback
* Better CHANGELOG links
* Better links
* code blocks
* Minor changes
* Correct links, comment out network section in 2.4
* Typos
* Revert non 2.4 changes
* Add placeholders for other items
* multiple inventory
* Update porting_guide_2.4.rst
* Update porting_guide_2.4.rst
* Update porting_guide_2.4.rst
* Update porting_guide_2.4.rst
* add win_command/win_shell escaping notes
* Added some windows porting info
* Edit for grammar
* Correct links, delete Net Platform Agnostic
* 2.5 link
* Network changes in 2.4
* facts_namespacing was pushed back to 2.5
Due to lack of time we pushed this back to 2.5 so that the facts in the namespace could be shortened.
* Python version
* Remove FIXMEs - move to seperate PR
* 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.
Fixes#29060
Allow delegate_to if transport is either nxapi or eapi.
Persistent connection uses `cli` transport and create
a local socket on control node. Hence delegate_to is not allowed
for `cli` transport.
However as `nxapi` and `eapi` transport does not use persistent connection
it is possible to use delegate_to in this case.
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.
* Use a rst glossary for playbooks_keywords docs
* Add a 'Task' and 'Tasks' to glossary.
* Update keywords desciptions,
* use :term: rst ref, some quoting
* Make it more obvious that 'retries' and 'until' need to be used in combination.
* let generate_man also gen rst pages for cli tools
* make template-file, output-dir, output format cli options for generate_man
* update main Makefile to use generate_man.py for docs (man pages and rst)
* update vault docs that use :option:
* Edits based on
6e34ea6242 and
a3afc78535
* add a optparse 'desc' to lib/ansible/cli/config.py
The man page needs a short desc for the 'NAME' field
which it gets from the option parse 'desc' value.
Fixes building ansible-config man page.
* add trim_docstring from pep257 to generate_man
use pep258 docstring trim function to fix up any indention
weirdness inherit to doc strings (ie, lines other than
first line being indented.
* Add refs to cli command actions
To reference ansible-vaults --vault-id option, use:
:option:`The link text here <ansible-vault --vault-id>`
or:
:option:`--vault-id <ansible-vault --vault-id>`
To reference ansible-vault's 'encrypt' action, use:
:ref:`The link text here <ansible_vault_encrypt>`
or most of the time:
:ref:`ansible-vault encrypt <ansible_vault_encrypt>`
Since json_query treats backticks as delimiters for literals,
some of the examples in the json_query docs can be made a little
simpler. Rather than replacing such examples, demonstrate the
alternative
scottb