* 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.
As outlined in https://docs.python.org/3.1/whatsnew/3.0.html#integers,
sys.maxint doesn't exist anymore in Python 3.x because there is no maximum
value for integers in Python 3.x. sys.maxsize is present in all
versions of Python that are currently supported by Ansible, so use that
instead as an arbitrarily large index value.
Fixes the following build error when building with Python 3.x:
make -j1 docs
mkdir -p ./docs/man/man1/ ; \
PYTHONPATH=./lib docs/bin/generate_man.py --template-file=docs/templates/man.j2 --output-dir=docs/man/man1/ --output-format man lib/ansible/cli/*.py
Traceback (most recent call last):
File "docs/bin/generate_man.py", line 253, in <module>
allvars[cli_name] = opts_docs(cli_class_name, cli_name)
File "docs/bin/generate_man.py", line 119, in opts_docs
'long_desc': trim_docstring(cli.__doc__),
File "docs/bin/generate_man.py", line 34, in trim_docstring
indent = sys.maxint
AttributeError: module 'sys' has no attribute 'maxint'
make: *** [Makefile:347: generate_asciidoc] Error 1
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
The variable was pointing to a file with a `.cer` extension but the curl command downloads a `.pem` file which makes executions of the bash script fail
* start rst docs for ansible-vault encrypt_string
* wip, vault format docs
(sorta markdown ish atm)
* wip - formatting
* wip, vault docs
* Fix refs to other docs for now
fixing default_role in conf.py will remove need
for this
* add 'ref' to cli names
* more vault docs
* wip, misc fixes
* add some encrypt_string examples
* Fix up rstcheck warnings
The code blocks in question included the output that would
be echo'ed from running the command, which isnt valid bash.
* fix formatting and rstcheck warnings about code-block
* Add envvar ref for ANSIBLE_VAULT_PASSWORD_FILE
* fix doc title
* Fixed title underline
* Edit pass for relocated community documentation.
* Updated info on Ansibullbot
Fixed improper link syntax
Change links to point to new documents
Changed Ansibot to Ansibullbot
Clarified workflow
Change formatting on commans and tags
* Update communication.rst
Add Contents
Use correct headings
* Update communication.rst
* Topics, remove whitespace, codeofconduct
* Formatting
* Correct heading
* Update maintainers.rst
* Minor edits and a request for more info
* Removed some hard-to-localize wording.
* Removed incomplete sentence
* Minor edits per review
* wip, gen docs from config/base.yml
* wip
* dont change conf.py here
* cleanup, add dump_config --template-file cli opt
* some desc are string, some are lists...
TODO: fix base.yml so it is consistent
* Filter out TODO and empty descriptions
* Can be set via env, credential profile, or module arg
* Valid values defined by Azure Python SDK, currently `AzureCloud`,`AzureChinaCloud`,`AzureUSGovernment`,`AzureGermanCloud` or any Azure Stack metadata discovery URL.
* Revise and link inline to the lists of modules
* Fix jinja2 objects.inv fallback path
* Fix bolding of deprecation marker
* Change module_support to link to lists via :doc:
That links to the top of the page instead of a section.
* Add a short text for each list of maintained modules
* Change maintenance info to only display on core and network modules
* Fix 'the the' typos, fix 'pahting' filename typo
* Change 'the the' typos to a single 'the'.
* Change `playbook_pahting.rst` to `playbook_pathing.rst`.
* Delete trailing space in ec2_vol example
Delete the trailing space in `instance: "{{ item.id }} "`, which makes the
example fail when run because it looks for instance "i-xxxx ".
This change fixes two issues with the generated return table:
1. When specifying a list of strings in the 'description' field of a
return value, it shows them in Python list syntax on the resulting
web page, e.g. `['a', 'b', 'c']`.
2. When specifying more than one line for the 'sample' field, the
result table gets damaged in the HTML output.
In addition, this change re-arranges the HTML tags produced in the
generated RST file such that they line up nicely and can better be
checked by humans for completeness.
Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>
* Use a template to generate the category lists
* Refactor so that we first extract all of the data that we need to
build the docs and then give that data to the templates to build with
* Add docs page listing modules ordered by support level
