From de652769def5b0f42ddf334e2ac74462abaff9c0 Mon Sep 17 00:00:00 2001
From: Karel van Klink <karel.vanklink@geant.org>
Date: Thu, 28 Dec 2023 17:25:53 +0100
Subject: [PATCH] update documentation

---
 docs/source/module/routes/index.rst           |  3 +-
 .../routes/{ip_trunk.rst => playbook.rst}     |  4 +-
 docs/source/module/routes/router.rst          |  6 ---
 docs/source/quickstart.rst                    | 38 +++++++++++++++++--
 lso/playbook.py                               |  5 +--
 lso/routes/playbook.py                        |  5 +--
 6 files changed, 41 insertions(+), 20 deletions(-)
 rename docs/source/module/routes/{ip_trunk.rst => playbook.rst} (50%)
 delete mode 100644 docs/source/module/routes/router.rst

diff --git a/docs/source/module/routes/index.rst b/docs/source/module/routes/index.rst
index 5adfbe1..1255547 100644
--- a/docs/source/module/routes/index.rst
+++ b/docs/source/module/routes/index.rst
@@ -13,5 +13,4 @@ Submodules
    :titlesonly:
 
    default
-   ip_trunk
-   router
+   playbook
diff --git a/docs/source/module/routes/ip_trunk.rst b/docs/source/module/routes/playbook.rst
similarity index 50%
rename from docs/source/module/routes/ip_trunk.rst
rename to docs/source/module/routes/playbook.rst
index c6c2e88..7a3da3c 100644
--- a/docs/source/module/routes/ip_trunk.rst
+++ b/docs/source/module/routes/playbook.rst
@@ -1,6 +1,6 @@
-``lso.routes.ip_trunk``
+``lso.routes.playbook``
 =======================
 
-.. automodule:: lso.routes.ip_trunk
+.. automodule:: lso.routes.playbook
    :members:
    :show-inheritance:
diff --git a/docs/source/module/routes/router.rst b/docs/source/module/routes/router.rst
deleted file mode 100644
index 2f10a49..0000000
--- a/docs/source/module/routes/router.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-``lso.routes.router``
-======================
-
-.. automodule:: lso.routes.router
-   :members:
-   :show-inheritance:
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
index f906ccb..ed6fe5d 100644
--- a/docs/source/quickstart.rst
+++ b/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
diff --git a/lso/playbook.py b/lso/playbook.py
index df3e038..0ada50b 100644
--- a/lso/playbook.py
+++ b/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`
     """
diff --git a/lso/routes/playbook.py b/lso/routes/playbook.py
index 0257cc4..4380887 100644
--- a/lso/routes/playbook.py
+++ b/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),
-- 
GitLab