Repository: ansible/ansible
Pull request: Added required parameter to document DOC-string to produce Documentation.

Signed-off-by: Satyajit Bulage <sbulage@redhat.com>

##### SUMMARY
<!--- Describe the change below, including rationale and design decisions -->
Fixes #64654
<!--- HINT: Include "Fixes #nnn" if you are fixing an existing issue -->

##### ISSUE TYPE
<!--- Pick one below and delete the rest -->
- Docs Pull Request


##### COMPONENT NAME
<!--- Write the short name of the module, plugin, task or feature below -->
template and win_template



Problem statement:
[WARNING]: template parsing did not produce documentation
<!--- Verify first that your issue is not already reported on GitHub -->
<!--- Also test if the latest release and devel branch are affected too -->
<!--- Complete *all* sections as described, this form is processed automatically -->

##### SUMMARY
<!--- Explain the problem briefly below -->

##### ISSUE TYPE
- Bug Report

##### COMPONENT NAME
<!--- Write the short name of the module, plugin, task or feature below, use your best guess if unsure -->

##### ANSIBLE VERSION
<!--- Paste verbatim output from "ansible --version" between quotes -->
```paste below

```

##### CONFIGURATION
<!--- Paste verbatim output from "ansible-config dump --only-changed" between quotes -->
```paste below

```

##### OS / ENVIRONMENT
<!--- Provide all relevant information below, e.g. target OS versions, network device firmware, etc. -->


##### STEPS TO REPRODUCE
<!--- Describe exactly how to reproduce the problem, using a minimal test-case -->

<!--- Paste example playbooks or commands between quotes below -->
```yaml

```

<!--- HINT: You can paste gist.github.com links for larger files -->

##### EXPECTED RESULTS
<!--- Describe what you expected to happen when running the steps above -->


##### ACTUAL RESULTS
<!--- Describe what actually happened. If possible run with extra verbosity (-vvvv) -->

<!--- Paste verbatim command output between quotes -->
```paste below

```
$ansible-doc -l | grep UNDOCUMENTED
[WARNING]: template parsing did not produce documentation.
[WARNING]: win_template parsing did not produce documentation.
template                                                      UNDOCUMENTED                                                   
win_template                                                  UNDOCUMENTED                                                   

There're 2 modules undocumented.

$ansible --version
ansible 2.9.0
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/smith/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.7/site-packages/ansible-2.9.0-py3.7.egg/ansible
  executable location = /usr/bin/ansible
  python version = 3.7.5 (default, Oct 21 2019, 7:17:39) [GCC 7.4.0]

#

Hints from issue discussion:
Files identified in the description:
None

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 --->
Both modules are in fact documented, you can view the documentation of each module by running: `ansible-doc template` and `ansible-doc win_template` or by visiting https://docs.ansible.com/ansible/latest/modules/template_module.html and https://docs.ansible.com/ansible/latest/modules/win_template_module.html.

The issue here is that both modules are missing the `short_description` field in the `DOCUMENTATION` string. `ansible-doc -l` uses `short_description` to indicate that the documentation is present, see the following function that does the work:

https://github.com/ansible/ansible/blob/0d851dda5968560ad64623bac66b82af8a167e3f/lib/ansible/parsing/plugin_docs.py#L86-L121

So the fix here appears to be adding `short_description` to https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/files/template.py and https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/windows/win_template.py files.
The short description exists, but it is currently located in a shared doc fragment: https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/doc_fragments/template_common.py#L14. To fix this, we can move the `short_description` from the shared fragment into the two module files.
- [ ] add short description to template module
- [ ] add short description to win_template module (possibly optimize it to mention Windows)
- [ ] remove short description from template_common doc fragment

Commit message: Added required parameter to document DOC-string to produce Documentation.

Signed-off-by: Satyajit Bulage <sbulage@redhat.com>

Patch to review:
diff --git a/lib/ansible/modules/files/template.py b/lib/ansible/modules/files/template.py
index 949c800ce69ee9..64c27a7f517270 100644
--- a/lib/ansible/modules/files/template.py
+++ b/lib/ansible/modules/files/template.py
@@ -17,6 +17,7 @@
 ---
 module: template
 version_added: historical
+short_description: Create a files and directories by using templates.
 options:
   follow:
     description:
diff --git a/lib/ansible/modules/windows/win_template.py b/lib/ansible/modules/windows/win_template.py
index dff65320a98d3f..b21a3b8422a7b3 100644
--- a/lib/ansible/modules/windows/win_template.py
+++ b/lib/ansible/modules/windows/win_template.py
@@ -13,6 +13,7 @@
 ---
 module: win_template
 version_added: "1.9.2"
+short_description: Create file from template or Backup given file.
 options:
   backup:
     description:
diff --git a/lib/ansible/plugins/doc_fragments/template_common.py b/lib/ansible/plugins/doc_fragments/template_common.py
index bf997ff744df7e..4481359ed1c1fa 100644
--- a/lib/ansible/plugins/doc_fragments/template_common.py
+++ b/lib/ansible/plugins/doc_fragments/template_common.py
@@ -11,8 +11,8 @@ class ModuleDocFragment(object):
 
     # Standard template documentation fragment, use by template and win_template.
     DOCUMENTATION = r'''
-short_description: Template a file out to a remote server
 description:
+- Template a file out to a remote server.
 - Templates are processed by the L(Jinja2 templating language,http://jinja.pocoo.org/docs/).
 - Documentation on the template formatting can be found in the
   L(Template Designer Documentation,http://jinja.pocoo.org/docs/templates/).


Code review comments:
diff_hunk: @@ -17,6 +17,7 @@
 ---
 module: template
 version_added: historical
+short_description: Create a files and directories by using templates.
path: lib/ansible/modules/files/template.py
text: @user1:
SHould just be what was on the original `short_description` in the template_common file.

diff_hunk: @@ -11,8 +11,8 @@ class ModuleDocFragment(object):
 
     # Standard template documentation fragment, use by template and win_template.
     DOCUMENTATION = r'''
-short_description: Template a file out to a remote server
 description:
+- Template a file out to a remote server.
path: lib/ansible/plugins/doc_fragments/template_common.py
text: @user1:
I don't think this is needed, seems like we just need to remove `short_description` here and just duplicate it across to `template.py` and `win_template.py`.

diff_hunk: @@ -13,6 +13,7 @@
 ---
 module: win_template
 version_added: "1.9.2"
+short_description: Create file from template or Backup given file.
path: lib/ansible/modules/windows/win_template.py
text: @user1:
Should just be what was on the original `short_description` in the template_common file.