T8989: vyos_hostname rework

1 files changed, 12 insertions, 140 deletions

diff --git a/docs/vyos.rest.vyos_hostname_module.rst b/docs/vyos.rest.vyos_hostname_module.rst
index c8ea1c5..7e4e37e 100644
--- a/docs/vyos.rest.vyos_hostname_module.rst
+++ b/docs/vyos.rest.vyos_hostname_module.rst
@@ -17,18 +17,10 @@ Version added: 1.0.0
 
 Synopsis
 --------
-- Manages the ``set system host-name`` configuration on a VyOS device using the HTTPS REST API.
-- Mirrors the behaviour of ``vyos.vyos.vyos_hostname`` but uses the HTTP API instead of SSH/network_cli.
-- The states ``replaced``, ``overridden`` behave identically to ``merged`` for this single-value resource.
+- Manages the ``system host-name`` configuration on a VyOS device using the HTTPS REST API.
 
 
 
-Requirements
-------------
-The below requirements are needed on the host that executes this module.
-
-- VyOS 1.3+
-
 
 Parameters
 ----------
@@ -44,21 +36,6 @@ Parameters
             <tr>
                 <td colspan="2">
                     <div class="ansibleOptionAnchor" id="parameter-"></div>
-                    <b>api_key</b>
-                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
-                    <div style="font-size: small">
-                        <span style="color: purple">string</span>
-                    </div>
-                </td>
-                <td>
-                </td>
-                <td>
-                        <div>API key configured on the device.</div>
-                </td>
-            </tr>
-            <tr>
-                <td colspan="2">
-                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                     <b>config</b>
                     <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                     <div style="font-size: small">
@@ -92,53 +69,6 @@ Parameters
             <tr>
                 <td colspan="2">
                     <div class="ansibleOptionAnchor" id="parameter-"></div>
-                    <b>hostname</b>
-                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
-                    <div style="font-size: small">
-                        <span style="color: purple">string</span>
-                    </div>
-                </td>
-                <td>
-                </td>
-                <td>
-                        <div>IP address or FQDN of the VyOS device (not needed with httpapi inventory).</div>
-                </td>
-            </tr>
-            <tr>
-                <td colspan="2">
-                    <div class="ansibleOptionAnchor" id="parameter-"></div>
-                    <b>port</b>
-                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
-                    <div style="font-size: small">
-                        <span style="color: purple">integer</span>
-                    </div>
-                </td>
-                <td>
-                        <b>Default:</b><br/><div style="color: blue">443</div>
-                </td>
-                <td>
-                        <div>HTTPS port for the REST API.</div>
-                </td>
-            </tr>
-            <tr>
-                <td colspan="2">
-                    <div class="ansibleOptionAnchor" id="parameter-"></div>
-                    <b>running_config</b>
-                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
-                    <div style="font-size: small">
-                        <span style="color: purple">string</span>
-                    </div>
-                </td>
-                <td>
-                </td>
-                <td>
-                        <div>Used only with state <code>parsed</code>.</div>
-                        <div>The value should be the output of <b>show configuration commands | grep host-name</b> from the device.</div>
-                </td>
-            </tr>
-            <tr>
-                <td colspan="2">
-                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                     <b>state</b>
                     <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                     <div style="font-size: small">
@@ -152,53 +82,13 @@ Parameters
                                     <li>overridden</li>
                                     <li>deleted</li>
                                     <li>gathered</li>
-                                    <li>rendered</li>
-                                    <li>parsed</li>
                         </ul>
                 </td>
                 <td>
                         <div><code>merged</code> - Ensure the hostname is set to the value in <em>config</em>.</div>
-                        <div><code>replaced</code> - Identical to <code>merged</code> for this single-value resource.</div>
-                        <div><code>overridden</code> - Identical to <code>merged</code> for this single-value resource.</div>
-                        <div><code>deleted</code> - Remove the configured hostname (resets to default).</div>
-                        <div><code>gathered</code> - Read the current hostname from the device and return it in <em>gathered</em> without making changes.</div>
-                        <div><code>rendered</code> - Return the CLI commands for the given config without connecting to the device.</div>
-                        <div><code>parsed</code> - Parse the <code>running_config</code> string and return structured data without connecting to the device.</div>
-                </td>
-            </tr>
-            <tr>
-                <td colspan="2">
-                    <div class="ansibleOptionAnchor" id="parameter-"></div>
-                    <b>timeout</b>
-                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
-                    <div style="font-size: small">
-                        <span style="color: purple">integer</span>
-                    </div>
-                </td>
-                <td>
-                        <b>Default:</b><br/><div style="color: blue">30</div>
-                </td>
-                <td>
-                        <div>Request timeout in seconds.</div>
-                </td>
-            </tr>
-            <tr>
-                <td colspan="2">
-                    <div class="ansibleOptionAnchor" id="parameter-"></div>
-                    <b>verify_ssl</b>
-                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
-                    <div style="font-size: small">
-                        <span style="color: purple">boolean</span>
-                    </div>
-                </td>
-                <td>
-                        <ul style="margin: 0; padding: 0"><b>Choices:</b>
-                                    <li><div style="color: blue"><b>no</b>&nbsp;&larr;</div></li>
-                                    <li>yes</li>
-                        </ul>
-                </td>
-                <td>
-                        <div>Validate the device&#x27;s TLS certificate.</div>
+                        <div><code>replaced</code> and <code>overridden</code> behave identically to <code>merged</code> for this single-value resource -- there is nothing else to distinctly replace or override when there is only one field.</div>
+                        <div><code>deleted</code> - Remove the configured hostname.</div>
+                        <div><code>gathered</code> - Read the current hostname from the device without making changes.</div>
                 </td>
             </tr>
     </table>
@@ -226,32 +116,14 @@ Examples
           hostname: vyos-core-01
         state: merged
 
-    - name: Replace hostname
-      vyos.rest.vyos_hostname:
-        config:
-          hostname: vyos-core-02
-        state: replaced
-
     - name: Gather current hostname
       vyos.rest.vyos_hostname:
         state: gathered
-      register: result
 
     - name: Delete hostname configuration
       vyos.rest.vyos_hostname:
         state: deleted
 
-    - name: Render commands without connecting
-      vyos.rest.vyos_hostname:
-        config:
-          hostname: vyos-core-01
-        state: rendered
-
-    - name: Parse running config
-      vyos.rest.vyos_hostname:
-        running_config: "set system host-name 'vyos'"
-        state: parsed
-
 
 
 Return Values
@@ -307,7 +179,7 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
                 </td>
                 <td>always</td>
                 <td>
-                            <div>REST API commands dispatched.</div>
+                            <div>List of API command tuples sent to the device.</div>
                     <br/>
                 </td>
             </tr>
@@ -329,30 +201,30 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
             <tr>
                 <td colspan="1">
                     <div class="ansibleOptionAnchor" id="return-"></div>
-                    <b>parsed</b>
+                    <b>response</b>
                     <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
                     <div style="font-size: small">
                       <span style="color: purple">dictionary</span>
                     </div>
                 </td>
-                <td>when state is parsed</td>
+                <td>when changes are applied</td>
                 <td>
-                            <div>Structured data parsed from running_config (state=parsed only).</div>
+                            <div>Raw API response.</div>
                     <br/>
                 </td>
             </tr>
             <tr>
                 <td colspan="1">
                     <div class="ansibleOptionAnchor" id="return-"></div>
-                    <b>rendered</b>
+                    <b>saved</b>
                     <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
                     <div style="font-size: small">
-                      <span style="color: purple">list</span>
+                      <span style="color: purple">boolean</span>
                     </div>
                 </td>
-                <td>when state is rendered</td>
+                <td>when changes are applied</td>
                 <td>
-                            <div>CLI commands for the provided config (state=rendered only).</div>
+                            <div>Whether the config was saved after changes.</div>
                     <br/>
                 </td>
             </tr>