Repository: ansible/ansible

Issue:
virt: documentation is too succinct
<!---
Verify first that your issue/request is not already reported on GitHub.
Also test if the latest release, and master branch are affected too.
-->

##### ISSUE TYPE
<!--- Pick one below and delete the rest -->
 - Documentation Report

##### COMPONENT NAME
<!---
Name of the module, plugin, task or feature
Do not include extra details here, e.g. "vyos_command" not "the network module vyos_command" or the full path
-->
virt

##### ANSIBLE VERSION
<!--- Paste verbatim output from "ansible --version" between quotes below -->
```
n/a
```

##### CONFIGURATION
<!---
If using Ansible 2.4 or above, paste the results of "ansible-config dump --only-changed"
Otherwise, mention any settings you have changed/added/removed in ansible.cfg
(or using the ANSIBLE_* environment variables).
-->
n/a

##### OS / ENVIRONMENT
<!---
Mention the OS you are running Ansible from, and the OS you are
managing, or say "N/A" for anything that is not platform-specific.
Also mention the specific version of what you are trying to control,
e.g. if this is a network bug the version of firmware on the network device.
-->
all

##### SUMMARY
<!--- Explain the problem briefly -->
The documentation for the `virt` module is too succinct. For example, it took me hours to disocver that unlike it's command line equivalent, virt define/create takes literal inline xml, not the path to an xml file like `virsh {define,create}`. Or that the `autostart` argument doesn't work with every command (try setting autostart while using define for instance)

##### STEPS TO REPRODUCE
<!---
For bugs, show exactly how to reproduce the problem, using a minimal test-case.
For new features, show how the feature would be used.
-->
cf. the virt module documentation

<!--- Paste example playbooks or commands between quotes below -->
```yaml

```

<!--- You can also paste gist.github.com links for larger files -->

##### EXPECTED RESULTS
<!--- What did you expect to happen when running the steps above? -->
More detailed documentation

##### ACTUAL RESULTS
<!--- What actually happened? If possible run with extra verbosity (-vvvv) -->
Confusion

<!--- Paste verbatim command output between quotes below -->
```

```

  


Discussion:
Files identified in the description:
* [lib/ansible/modules/cloud/misc/virt.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/cloud/misc/virt.py)

If these files are inaccurate, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
@coaxial Do you have an example task which has the XML in it? I'm open to helping to revise this, but I'm curious to see if you have something which would make it easier to revise.

Regarding `autostart` does it only work on its own or can it co-exist with other parameters? I looked at the source quickly and didn't see any obvious exclusions but curious about your experience.

I'm still figuring out the virt module on my own and haven't gotten as far as you. But I'll probably be doing some experiments to refine this documentation.
@kbreit Yes, cf. https://github.com/coaxial/ansible-playbooks/blob/master/create-vm/playbook.yml#L73. i.e. you souldn't supply the path to the xml file but rather output the actual xml (which is what lookup does)

I don't remember if autostart works on its own. I couldn't figure out how to use it so instead I'm using `virsh autostart` from the shell (https://github.com/coaxial/ansible-playbooks/blob/master/create-vm/playbook.yml#L85)
Reverse order. Your playbook does autostart on its own, so that's something.

Regarding line 73 in your playbook, the example at the bottom shows the use of `lookup()` so that's accurate, but the description is poor. I think the comments for `xml` can be updated to "XML document used for the define command. Must be raw XML content using `lookup()`. XML cannot be reference to a file."

Do you feel this clears up your concern?
Yes, I think that would help clarify that part.

Resolving patch:
diff --git a/lib/ansible/modules/cloud/misc/virt.py b/lib/ansible/modules/cloud/misc/virt.py
--- a/lib/ansible/modules/cloud/misc/virt.py
+++ b/lib/ansible/modules/cloud/misc/virt.py
@@ -48,6 +48,7 @@
   xml:
     description:
       - XML document used with the define command.
+      - Must be raw XML content using C(lookup). XML cannot be reference to a file.
 requirements:
     - python >= 2.6
     - libvirt-python


Test patch: