Add basic scenario guides (#36)

* Add extra docs.

* Mention more quirks.

* Work around RST quirks.

docs/docsite/extra-docs.yml

@@ -0,0 +1,6 @@
+---
+sections:
+  - title: Guides
+    toctree:
+      - api-guide
+      - ssh-guide

docs/docsite/rst/api-guide.rst

@@ -0,0 +1,51 @@
+.. _ansible_collections.community.routeros.docsite.api-guide:
+
+How to connect to RouterOS devices with the RouterOS API
+========================================================
+
+You can use the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` to connect to a RouterOS device with the RouterOS API.
+
+No special setup is needed; the module needs to be run on a host that can connect to the device's API. The most common case is that the module is run on ``localhost``, either by using ``hosts: localhost`` in the playbook, or by using ``delegate_to: localhost`` for the task. The following example shows how to run the equivalent of ``/ip address print``:
+
+.. code-block:: yaml+jinja
+
+    ---
+    - name: RouterOS test with API
+      hosts: localhost
+      gather_facts: no
+      vars:
+        hostname: 192.168.1.1
+        username: admin
+        password: test1234
+      tasks:
+        - name: Get "ip address print"
+          community.routeros.api:
+            hostname: "{{ hostname }}"
+            password: "{{ password }}"
+            username: "{{ username }}"
+            path: "ip address"
+            ssl: true
+          register: print_path
+
+    - name: Show IP address of first interface
+      debug:
+        msg: "{{ print_path.msg[0].address }}"
+
+This results in the following output:
+
+.. code-block:: ansible-output
+
+    PLAY [RouterOS test] *********************************************************************************************
+
+    TASK [Get "ip address print"] ************************************************************************************
+    ok: [localhost]
+
+    TASK [Show IP address of first interface] ************************************************************************
+    ok: [localhost] => {
+        "msg": "192.168.2.1/24"
+    }
+
+    PLAY RECAP *******************************************************************************************************
+    localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
+
+Check out the documenation of the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` for details on the options.

docs/docsite/rst/ssh-guide.rst

@@ -0,0 +1,122 @@
+.. _ansible_collections.community.routeros.docsite.ssh-guide:
+
+How to connect to RouterOS devices with SSH
+===========================================
+
+The collection offers two modules to connect to RouterOS devies with SSH:
+
+- The :ref:`community.routeros.facts module <ansible_collections.community.routeros.facts_module>` gathers facts about a RouterOS device;
+- The :ref:`community.routeros.command module <ansible_collections.community.routeros.command_module>` executes commands on a RouterOS device.
+
+The modules need the :ref:`ansible.netcommon.network_cli connection plugin <ansible_collections.ansible.netcommon.network_cli_connection>` for this.
+
+Important notes
+---------------
+
+1. The SSH-based modules do not support arbitrary symbols in the router's identity. If you are having trouble connecting to your device, please make sure that your MikroTik's identity contains only alphanumeric characters and dashes. Also make sure that the identity string is not longer than 19 characters (`see issue for details <https://github.com/ansible-collections/community.routeros/issues/31>`__). Similar problems can happen for unsupported characters in your username.
+
+2. The :ref:`community.routeros.command module <ansible_collections.community.routeros.command_module>` does not support nesting commands and expects every command to start with a forward slash (``/``). Running the following command will produce an error:
+
+   .. code-block:: yaml+jinja
+
+       - community.routeros.command:
+           commands:
+             - /ip
+             - print
+
+3. When using the :ref:`community.routeros.command module <ansible_collections.community.routeros.command_module>` module, make sure to not specify too long commands. Alternatively, add something like ``+cet512w`` to the username (replace ``admin`` with ``admin+cet512w``) to tell RouterOS to not wrap before 512 characters in a line (`see issue for details <https://github.com/ansible-collections/community.routeros/issues/6>`__).
+
+4. Finally, the :ref:`ansible.netcommon.network_cli connection plugin <ansible_collections.ansible.netcommon.network_cli_connection>` uses `paramiko <https://pypi.org/project/paramiko/>`_ by default to connect to devices with SSH. You can set its ``ssh_type`` option to ``libssh`` to use `ansible-pylibssh <https://pypi.org/project/ansible-pylibssh/>`_ instead, which offers Python bindings to libssh. See its documentation for details.
+
+Setting up an inventory
+-----------------------
+
+An example inventory ``hosts`` file for a RouterOS device is as follows:
+
+.. code-block:: ini
+
+    [routers]
+    router ansible_host=192.168.2.1
+
+    [routers:vars]
+    ansible_connection=ansible.netcommon.network_cli
+    ansible_network_os=community.routeros.routeros
+    ansible_user=admin
+    ansible_ssh_pass=test1234
+
+This tells Ansible that you have a RouterOS device called ``router`` with IP ``192.168.2.1``. Ansible should use the :ref:`ansible.netcommon.network_cli connection plugin <ansible_collections.ansible.netcommon.network_cli_connection>` together with the the :ref:`community.routeros.routeros cliconf plugin <ansible_collections.community.routeros.routeros_cliconf>`. The credentials are stored as ``ansible_user`` and ``ansible_ssh_pass`` in the inventory.
+
+Connecting to the device
+------------------------
+
+With the above inventory, you can use the following playbook to execute ``/system resource print`` on the device
+
+.. code-block:: yaml+jinja
+
+    ---
+    - name: RouterOS test with network_cli connection
+      hosts: routers
+      gather_facts: false
+      tasks:
+
+      - name: Gather system resources
+        community.routeros.command:
+          commands:
+            - /system resource print
+        register: system_resource_print
+
+      - name: Show system resources
+        debug:
+          var: system_resource_print.stdout_lines
+
+      - name: Gather facts
+        community.routeros.facts:
+
+      - name: Show a fact
+        debug:
+          msg: "First IP address: {{ ansible_net_all_ipv4_addresses[0] }}"
+
+This results in the following output:
+
+.. code-block:: ansible-output
+
+    PLAY [RouterOS test with network_cli connection] *****************************************************************
+
+    TASK [Gather system resources] ***********************************************************************************
+    ok: [router]
+
+    TASK [Show system resources] *************************************************************************************
+    ok: [router] => {
+        "system_resource_print.stdout_lines": [
+            [
+                "uptime: 3d10h28m51s",
+                "                  version: 6.48.3 (stable)",
+                "               build-time: May/25/2021 06:09:45",
+                "              free-memory: 31.2MiB",
+                "             total-memory: 64.0MiB",
+                "                      cpu: MIPS 24Kc V7.4",
+                "                cpu-count: 1",
+                "            cpu-frequency: 400MHz",
+                "                 cpu-load: 1%",
+                "           free-hdd-space: 54.2MiB",
+                "          total-hdd-space: 128.0MiB",
+                "  write-sect-since-reboot: 927",
+                "         write-sect-total: 51572981",
+                "               bad-blocks: 1%",
+                "        architecture-name: mipsbe",
+                "               board-name: RB750GL",
+                "                 platform: MikroTik"
+            ]
+        ]
+    }
+
+    TASK [Gather facts] **********************************************************************************************
+    ok: [router]
+
+    TASK [Show a fact] ***********************************************************************************************
+    ok: [router] => {
+        "msg": "First IP address: 192.168.2.1"
+    }
+
+    PLAY RECAP *******************************************************************************************************
+    router                     : ok=4    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0