Raise the bar for module `DOCUMENTAION`
This validator update was used to find the issues in https://github.com/ansible/ansible/pull/22297/files
**Validation**
* Updated Validation and docs to enforce more (items fixed in https://github.com/ansible/ansible/pull/22297/files)
* Use `suboptions` to document complex options
* Validate module name
* Validate deprecated modules have correct ANSIBLE_METADATA
**Module Documentation Generation**
* Document `suboptions:` Example https://gist.github.com/gundalow/4bdc3669d696268328ccc18528cc6718
* Tidy up HTML generation (valid HTML, no empty lists, etc)
**Documentation**
* Clarify the steps for deprecating a module
* Use correct RST headings
* Document `suboptions:` (options)
* Document `contains:` (returns)
**Details**
The aim is to get this (and corresponding module updates) complete by the time `devel` becomes `2.4`, as this allows us to raise the bar for new modules
Example `suboptions` https://gist.github.com/gundalow/4bdc3669d696268328ccc18528cc6718
The aim is to get this PR integrated into `devel` *before* we branch `stable-2.3`, this will allows us to:
* Raise the bar for new modules in 2.4
* Ensure the generated module documentation for 2.3 and higher is improved, important as we will be doing versioned docs moving forward.
added docs for new v2 features
restructures modules bar and core/extras info into their own pages
changed templates to refer to the new pages
added some missing ansible.cfg options
more info on gathering setting
now version_added < 1.3 does not get shown, up from 1.0
option's version_added is also now filterd against this threshold
module version_added is more prominent
exaples now uses pure rst instead of intermingled with html formatting
aliases now shown in description for options
bad version fields now throw warnings instead of exceptions
ansible-doc errors now show traceback in very very verbose mode, for easier debugging
- clearer 'version added' for module options, now it sits under the option name
- made notes a section, so it now appears in toc
- moved requirements and made it a list, more prominent and more readable
There was a missing trailing underscore (`_`) that would have marked the
content in the backticks as a link. This adds it and fixes the link on
every core module page.
Contributors are still listed on github module source and in repo, and original authors still in the file for when development questions arise, but want
to funnel support questions to the mailing list versus directly to them.
Add HTML-escaping to code examples in rST tempate of module-formatter
Add support for specifying port, addresses with phrases and attaching files
Add support for custom headers and document version_added for new options
X-Mailer header added :)
protect empty address lists & attachment list, and add bcc
- fixed template (it was the template), adding indentation with Jinja2
- added description of code examples to man-page template (was missing)
- fixed fireball, cron, and debug module examples to confrom
