Co-authored-by: Matt Clay <matt@mystile.com>
Co-authored-by: Matt Davis <mrd@redhat.com>
Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
* ensure dump produces json
* clog and tests
* remove library additions since they are not usable
* avoid any/all dirs
* ensure we dont use local dir as playbookdir
* Fix struture of cli/doc.py snippet code.
A couple releases ago, cli/doc.py was modified to mostly conform to the
data processing pipeline steps. format_plugin_doc() was the biggest
exception in that refactor. When the snippet code was made generic
instead of being only for modules, the new code should have conformed to
the data processing pipeline too.
* Move the decision to output a snippet to the run() method alongside
the decision to output a listing versus plugin_docs.
* Move the test for invalid plugin_types to the run() method as it
affects all snippets in this run, not just a single snippet. (-t can
only be specified once)
* Rename get_snippet_text() to format_snippet() as:
* This is the data formatting step
* The format_snippet() name matches with its conceptual sibling,
format_plugin_doc().
* Use ValueError inside of format_snippet() to flag unrecoverable errors
formatting a single snippet.
* Emit a warning when format_snippet() raises ValueError and continue to
the next snippet.
* If the yaml(?) or toml inventory plugin is specified for snippet output,
raise ValueError() so that the user sees a warning instead of simply
seeing blank output.
* Do not modify arguments passed into format_snippet(). This is the
formatting step so data should not be modified.
* Change _do_yaml_snippet() and _do_lookup_snippet() to operate side
effect free.
* Fix raising of exceptions when formatting requred options for snippets.
* Unrelated: Use to_text() instead of to_native when calling
display.warning(). to_native() is used for raising exceptions. Not
for display methods.
* Add a changelog
cli options will now display either use provided info, or automating from the name
Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
* support separate role argspec file in ansible-doc
* support separate role argspec file in ansible-core
* support both .yml and .yaml extensions on argspec file in ansible-doc
* fix filename building bug and rename some argspec files to test variations
* use yaml extensions from constants
* add superfluous meta/main.yml files to tests
* Update lib/ansible/cli/doc.py
Co-authored-by: Sam Doran <sdoran@redhat.com>
* update docs
* ci_complete
* add changelog and allow for main.yml variations
* add collection role testing
Co-authored-by: Sam Doran <sdoran@redhat.com>
* Add yaml utils file and use it
* Linting fix and missing import
* Abstract a few more details
* Parser imports
* Don't use CSafeDumper in AnsibleDumper
* Move and use convert_yaml_objects_to_native when libyaml is present
* yaml_load and yaml_dump, instead of safe_*
* re-use HAS_LIBYAML from utils.yaml
* add changelog fragment
* Address recent changes
* Use representer instead of recursive type converter
* Restore needed import
* move yaml utils to module_utils
* Properly guard imports
* Update from_yaml(_all)? to handle text wrappers with CSafeLoader
* Use yaml utils for legacy_collection_loader
* Add HAS_YAML, and ignore pylint issue
* oops
* GPL->BSD
* Change role argspec file used by ansible-doc
This changes the file used for role argument specs from meta/argument_specs.yml
to meta/main.yml. The argument specs are expected to be in that file under the
top-level entry of `argument_spec`.
* Switch to argument_specs
* Support listing roles in text and JSON
* Change tests for unfrack'd playbook_dir var
These tests were using '/tmp' for testing the setting of the playbook_dir
var. Now that we unfrack that var, MacOS will change this to '/private/tmp'
causing the tests to fail. We can choose a path that does not exist (since
unfrack does not validate existence) so that we can guarantee unfracking
will not change the value.
* ansible-doc: export has_action when --json is used.
* Remove docuri and now_data, which were not used resp. ignored in format_plugin_doc and the functions it calls anyway.
* Add function _combine_plugin_doc.
* 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>
* ansible-doc man formatter: do not crash when description isn't there.
* Change to report a better error message when description is not there.
* Add test.
* Tag return value docs if they are a dict (and not str/None).
* Try to parse return docs as YAML.
* Properly dump return values in ansible-doc.
* Adjust plugin formatter.
* Add changelog fragment.
* Don't add 'default' for return values.
* Fix plugin_formatter.
* Only try to parse return docs if they are still a string.
* Add tests.
* Warn if RETURN cannot be parsed.
* Adjust tests. Also test for warning.
* if -> elif (otherwise EXAMPLE will be parsed too).
* Always parse return documentation, and fail if it is invalid YAML.
* Polishing.
* Mostly re-enable ansible-doc tests.
Listing from the local collection seems to be somewhat broken. I assume this
is why the test was disabled.
* Lint and make tests work with Python 2.
* Keep FQCNs in plugins (not modules), i.e. restore previous state.
* Support removed_at_date in ansible-doc
Signed-off-by: NilashishC <nilashishchakraborty8@gmail.com>
Changes:
* ansible-doc does not support `removed_at_date` and assumes that
deprecated dict will either have `removed_in` or `version`. This
results in ansible-doc (and hence "sanity --test=ansible-doc")
failing for modules having only `removed_at_date`.
* This patch adds support for `removed_at_date` and also gives it
precedence over `removed_in` or `version`.
* Add tests and changelog
Signed-off-by: NilashishC <nilashishchakraborty8@gmail.com>
* Allow to specify collection_name separately for deprecation.
* Use new functionality in Ansible.
* Use new functionality in tests.
* Update tagging/untagging functions.
* Update pylint deprecated sanity test.
* Update validate-modules. Missing are basic checks for version_added (validate semantic version format for collections).
* Improve version validation. Re-add version_added validation.
* Make sure collection names are added to return docs before schema validation.
* Extra checks to avoid crashes on bad data.
* Make C# module utils code work, and update/extend tests.
* Add changelog fragment.
* Stop extracting collection name from potentially tagged versions/dates.
* Simplify C# code.
* Update Windows modules docs.
* Forgot semicolons.
* starting metadata sunset
- purged metadata from any requirements
- fix indent in generic handler for yaml content (whey metadata display was off)
- make more resilient against bad formed docs
- removed all metadata from docs template
- remove metadata from schemas
- removed mdata tests and from unrelated tests
Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Rick Elrod <rick@elrod.me>
* Track collection for version_added.
Validate *all* version numbers in validate-modules.
For tagged version numbers (i.e. version_added), consider source collection to chose validation.
* Make tagging/untagging functions more flexible.
* Tag all versions in doc fragments.
* Tag all deprecation versions issued by code.
* Make Display.deprecated() understand tagged versions.
* Extend validation to enforce tagged version numbers.
* Tag versions in tests.
* Lint and fix test.
* Mention collection name in collection loader's deprecation/removal messages.
* Fix error IDs.
* Handle tagged dates in Display.deprecated().
* Also require that removed_at_date and deprecated_aliases.date are tagged.
* Also automatically tag/untag removed_at_date; fix sanity module removal version check.
* Improve error message when invalid version number is used (like '2.14' in collections).
* `meta/` directory in collections
* runtime metadata for redirection/deprecation/removal of plugin loads
* a compatibility layer to keep existing content working on ansible-base + collections
* a Python import redirection layer to keep collections-hosted (and otherwise moved) content importable by things that don't know better
* supported Ansible version validation on collection loads
* Add integration tests for ansible-doc.
* Enable tests that now pass
* Cleanup processing of plugin docs
* Mostly separate the steps of processing plugin docs
1) Acquire source data
2) Transform and calculate additonal data
3) Format data for output
4) Output data
format_plugin_doc() is still mixing transformation and formatting but
that should be fixed in a devel-only change
* Raise exceptions in _get_plugin_doc() on errors.
* Remove check to exclude on blacklisted extensions. We already request
only .py files
* If there is no DOCUMENTATION entry in the plugin, raise an exception
from _get_plugin_doc(). Everywhere we use _get_plugin_doc(), this is
treated as an error
* If there is no ANSIBLE_METADATA raise an exception as well as
displaying of docs assumes that this has been set.
* If there is neither DOCUMENTATION nor ANSIBLE_METADATA, warn about the
lack of METADATA and error on the lack of DOCUMENTATION. Lack of
DOCUMENTATION is more important so it is what the user should see.
* Add a few special cases for backwards compat. These should probably
be made errors in 2.10:
* no docs but has metadata shows no documentation rather than an error
* empty plugin file shows no doumentation rather than an error
* Simplify backwards compatibility logic.
* Fix ansible-doc traceback for removed modules.
This avoids tracebacks with errors like the following when a module has been removed:
module module_name missing documentation (or could not parse documentation): 'NoneType' object does not support item assignment
* Fix ansible-doc sanity test warning handling.
Warnings about removed modules/plugins on stderr are now properly ignored.
Previously an ansible-doc error could result in unrelated errors going undetected because tests were stopped early and the underlying error was ignored.
* Start of migration to argparse
* various fixes and improvements
* Linting fixes
* Test fixes
* Fix vault_password_files
* Add PrependAction for argparse
* A bunch of additional tweak/fixes
* Fix ansible-config tests
* Fix man page generation
* linting fix
* More adhoc pattern fixes
* Add changelog fragment
* Add support for argcomplete
* Enable argcomplete global completion
* Rename PrependAction to PrependListAction to better describe what it does
* Add documentation for installing and configuring argcomplete
* Address rebase issues
* Fix display encoding for vault
* Fix line length
* Address rebase issues
* Handle rebase issues
* Use mutually exclusive group instead of handling manually
* Fix rebase issues
* Address rebase issue
* Update version added for argcomplete support
* -e must be given a value
* ci_complete
Matt Martz