update documentation

docs/source/module/routes/index.rst

@@ -13,5 +13,4 @@ Submodules
    :titlesonly:
 
    default
-   ip_trunk
-   router
+   playbook

docs/source/module/routes/ip_trunk.rst → docs/source/module/routes/playbook.rst

-``lso.routes.ip_trunk``
+``lso.routes.playbook``
 =======================
 
-.. automodule:: lso.routes.ip_trunk
+.. automodule:: lso.routes.playbook
    :members:
    :show-inheritance:

docs/source/module/routes/router.rst

-``lso.routes.router``
-======================
-
-.. automodule:: lso.routes.router
-   :members:
-   :show-inheritance:

docs/source/quickstart.rst

@@ -3,14 +3,44 @@ Quick start
 
 This is a quick setup guide for running standalone on your local machine.
 
+As a Docker container
+---------------------
+To run LSO as a Docker container, build an image using the ``Dockerfile`` as an example. Be sure to update
+``ansible-galaxy-requirements.yaml`` accordingly, depending on your specific Ansible collection and -role needs.
+
+An example Docker compose file is presented below:
+
+.. code-block:: yaml
+
+   version: "3.5"
+   services:
+     lso:
+       image: goat-lso:$LSO_VERSION_TAG
+       environment:
+         SETTINGS_FILENAME: /app/config.json
+       volumes:
+         - "/home/user/config.json:/app/config.json:ro"
+         - "/home/user/ansible_inventory:/opt/ansible_inventory:ro"
+         - "~/.ssh/id_ed25519.pub:/root/.ssh/id_rsa.pub:ro"
+         - "~/.ssh/id_ed25519:/root/.ssh/id_rsa:ro"
+       restart: unless-stopped
+
+This will expose the API on port 8080. The container requires some additional files to be mounted:
+
+* A ``config.json`` that references to the location where the Ansible playbooks are stored **inside the container**.
+* An Ansible inventory for all host and group variables that are used in the playbooks
+* A public/private key pair for SSH authentication on external machines that are targeted by Ansible playbooks.
+
 Install the module
 ------------------
 
+Alternatively, below are a set of instructions for installing and running LSO directly on a machine.
+
 *One of these should be what you're looking for:*
 
 * Install the latest module snapshot
 
-.. code-block::
+.. code-block:: bash
 
     python3 -m venv my-venv-directory
     . my-venv-directory/bin/activate
@@ -19,12 +49,12 @@ Install the module
 
 * Install the source code
 
-.. code-block::
+.. code-block:: bash
 
     python3 -m venv my-venv-directory
     . my-venv-directory/bin/activate
 
-    git clone https://gitlab.geant.org/goat/gap/lso.git
+    git clone https://gitlab.software.geant.org/goat/gap/lso.git
     cd lso
     pip install -e .
 
@@ -50,4 +80,4 @@ Examples
 
      curl http://localhost:44444/api/version
 
-* View the docs by loading <http://localhost:44444/docs> in your browser
+* View the docs by loading http://localhost:44444/docs in your browser

lso/playbook.py

@@ -88,9 +88,8 @@ def run_playbook(
     :param Path playbook_path: playbook to be executed.
     :param dict[str, Any] extra_vars: Any extra vars needed for the playbook to run.
     :param dict[str, Any] | str inventory: The inventory that the playbook is executed against.
-    :param :class:`HttpUrl` callback: Callback URL where the playbook should send a status update when execution is
-                                      completed. This is used for workflow-orchestrator to continue with the next step
-                                      in a workflow.
+    :param HttpUrl callback: Callback URL where the playbook should send a status update when execution is completed.
+                             This is used for workflow-orchestrator to continue with the next step in a workflow.
     :return: Result of playbook launch, this could either be successful or unsuccessful.
     :rtype: :class:`fastapi.responses.JSONResponse`
     """

lso/routes/playbook.py

@@ -67,9 +67,8 @@ def run_playbook_endpoint(params: PlaybookRunParams) -> JSONResponse:
 
     The response will contain either a job ID, or error information.
 
-    :param params :class:`PlaybookRunParams`: Parameters for executing a playbook.
-    :return: Response from the Ansible runner, including a run ID.
-    :rtype: :class:`fastapi.responses.JSONResponse`
+    :param PlaybookRunParams params: Parameters for executing a playbook.
+    :return JSONResponse: Response from the Ansible runner, including a run ID.
     """
     return run_playbook(
         playbook_path=get_playbook_path(params.playbook_name),