Merge pull request #38 from lkubb/fix/docs-rendering

CHANGELOG.md

@@ -4,7 +4,7 @@ This project uses [Semantic Versioning](https://semver.org/) - MAJOR.MINOR.PATCH
 
 # Changelog
 
-# Saltext.Proxmox 1.1.0 (2023-10-11)
+## v1.1.0 (2023-10-11)
 
 ### Removed
 
@@ -21,7 +21,7 @@ This project uses [Semantic Versioning](https://semver.org/) - MAJOR.MINOR.PATCH
 - fixed location parameter for `avail_images()` (#25)
 
 
-# Saltext.Proxmox 1.0.0 (2023-04-26)
+## v1.0.0 (2023-04-26)
 
 ### Added
 

docs/conf.py

@@ -126,8 +126,6 @@
 
 autosummary_generate = False
 
-suppress_warnings = ["myst.header"]
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/index.rst

@@ -9,7 +9,7 @@ Salt Extension for interacting with Proxmox PVE
   :hidden:
 
   topics/installation
-  topics/index
+  topics/configuration
 
 .. toctree::
   :maxdepth: 2

docs/topics/configuration.md

@@ -0,0 +1,98 @@
+# Configuration
+
+## Provider
+Set up the cloud configuration at `/etc/salt/cloud.providers` or `/etc/salt/cloud.providers.d/proxmox.conf`:
+
+```yaml
+my-proxmox-config:
+  # Required parameters
+  user: myuser@pam  # or myuser@pve
+  token: myapitoken
+  url: https://hypervisor.domain.tld:8006
+  driver: proxmox
+```
+
+## Profile examples
+### Create a new LXC container
+```yaml
+my-lxc-container:
+  provider: my-proxmox-config
+  technology: lxc
+
+  # Required for cloud.bootstrap()
+  ssh_host: 192.168.101.2
+  ssh_username: root
+  ssh_password: supersecret
+
+  create:
+    # For parameters check https://<PROXMOX_URL>/pve-docs/api-viewer/index.html#/nodes/{node}/lxc
+    vmid: 123
+    ostemplate:  local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst
+    node: proxmox-node1
+
+    hostname: my-lxc-container
+    net0: name=eth0,bridge=vmbr0,firewall=1,gw=192.168.101.1,ip=192.168.101.2/24,tag=101,type=veth
+    password: supersecret
+```
+
+### Clone an existing LXC container
+```yaml
+my-lxc-container:
+  provider: my-proxmox-config
+  technology: lxc
+
+  # Required for cloud.bootstrap()
+  ssh_host: 192.168.101.2
+  ssh_username: root
+  ssh_password: supersecret
+
+  clone:
+    # For parameters check https://<PROXMOX_URL>/pve-docs/api-viewer/index.html#/nodes/{node}/lxc/clone
+    vmid: 123
+    newid: 456
+    node: proxmox-node1
+
+    hostname: my-lxc-container
+    description: cloned vm
+```
+
+### Create a new QEMU VM
+```yaml
+my-qemu-vm:
+  provider: my-proxmox-config
+  technology: qemu
+
+  # Required for cloud.bootstrap()
+  ssh_host: 192.168.101.2
+  ssh_username: root
+  ssh_password: supersecret
+
+  create:
+    # For parameters check https://<PROXMOX_URL>/pve-docs/api-viewer/index.html#/nodes/{node}/qemu
+    vmid: 123
+    node: proxmox-node1
+
+    name: my-qemu-vm
+    ipconfig0: ip=192.168.101.2/24,gw=192.168.101.1
+```
+
+### Clone an existing QEMU VM
+```yaml
+my-qemu-vm:
+  provider: my-proxmox-config
+  technology: qemu
+
+  # Required for cloud.bootstrap()
+  ssh_host: 192.168.101.2
+  ssh_username: root
+  ssh_password: supersecret
+
+  clone:
+    # For parameters check https://<PROXMOX_URL>/pve-docs/api-viewer/index.html#/nodes/{node}/qemu/clone
+    vmid: 123
+    newid: 456
+    node: proxmox-node1
+
+    name: my-qemu-vm
+    description: cloned vm
+```

src/saltext/proxmox/clouds/proxmox.py

@@ -1,116 +1,12 @@
 """
 Proxmox Cloud Module
-======================
+====================
 
-The Proxmox cloud module is used to control access to Proxmox
+The Proxmox cloud module is used to control access to Proxmox.
 
-Set up the cloud configuration at ``/etc/salt/cloud.providers`` or
- ``/etc/salt/cloud.providers.d/proxmox.conf``:
-
-.. code-block:: yaml
-
-    my-proxmox-config:
-      # Required parameters
-      user: myuser@pam # or myuser@pve
-      token: myapitoken
-      url: https://hypervisor.domain.tld:8006
-      driver: proxmox
-
-This cloud module is a wrapper for the Proxmox API. As such, all supported parameters for VM operations (create, clone, start, ...) by the Proxmox API are also supported through this cloud module.
-
-Profile configuration examples:
-
-Create a new LXC container
---------------------------
-
-.. code-block:: yaml
-
-    my-lxc-container:
-        provider: my-proxmox-config
-        technology: lxc
-
-        # Required for cloud.bootstrap()
-        ssh_host: 192.168.101.2
-        ssh_username: root
-        ssh_password: supersecret
-
-        create:
-            # For parameters check https://<PROXMOX_URL>/pve-docs/api-viewer/index.html#/nodes/{node}/lxc
-            vmid: 123
-            ostemplate:  local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst
-            node: proxmox-node1
-
-            hostname: my-lxc-container
-            net0: name=eth0,bridge=vmbr0,firewall=1,gw=192.168.101.1,ip=192.168.101.2/24,tag=101,type=veth
-            password: supersecret
-
-Clone an existing LXC container
--------------------------------
-
-.. code-block:: yaml
-
-   my-lxc-container:
-        provider: my-proxmox-config
-        technology: lxc
-
-        # Required for cloud.bootstrap()
-        ssh_host: 192.168.101.2
-        ssh_username: root
-        ssh_password: supersecret
-
-        clone:
-            # For parameters check https://<PROXMOX_URL>/pve-docs/api-viewer/index.html#/nodes/{node}/lxc/clone
-            vmid: 123
-            newid: 456
-            node: proxmox-node1
-
-            hostname: my-lxc-container
-            description: cloned vm
-
-Create a new QEMU VM
---------------------
-
-.. code-block:: yaml
-
-    my-qemu-vm:
-        provider: my-proxmox-config
-        technology: qemu
-
-        # Required for cloud.bootstrap()
-        ssh_host: 192.168.101.2
-        ssh_username: root
-        ssh_password: supersecret
-
-        create:
-            # For parameters check https://<PROXMOX_URL>/pve-docs/api-viewer/index.html#/nodes/{node}/qemu
-            vmid: 123
-            node: proxmox-node1
-
-            name: my-qemu-vm
-            ipconfig0: ip=192.168.101.2/24,gw=192.168.101.1
-
-Clone an existing QEMU VM
--------------------------
-
-.. code-block:: yaml
-
-    my-qemu-vm:
-        provider: my-proxmox-config
-        technology: qemu
-
-        # Required for cloud.bootstrap()
-        ssh_host: 192.168.101.2
-        ssh_username: root
-        ssh_password: supersecret
-
-        clone:
-            # For parameters check https://<PROXMOX_URL>/pve-docs/api-viewer/index.html#/nodes/{node}/qemu/clone
-            vmid: 123
-            newid: 456
-            node: proxmox-node1
-
-            name: my-qemu-vm
-            description: cloned vm
+This cloud module is a wrapper for the Proxmox API. As such, all supported parameters
+for VM operations (create, clone, start, ...) by the Proxmox API are also
+supported through this cloud module.
 
 :maintainer: EITR Technologies, LLC <[email protected]>
 :depends: requests >= 2.2.1