Merge pull request #25 from OSLA-project/18-explain-how-to-adapt-quickstart-to-your-own-lab

18 explain how to adapt quickstart to your own lab

Author: dsmits

docs/customization.md

@@ -0,0 +1,54 @@
+# Customization
+To customize the simulated example to your own needs, you will need to take a couple of steps.
+
+- [Find lab resource classes](#resource_classes)
+- [Find or implement lab SiLA servers](#sila_servers)
+- [Write your device wrappers](#device_wrappers)
+- [Configure your lab definition](#lab_definition)
+- [Write your process descriptions](#process_descriptions)
+- [Customize the robot arm](#robot_arm)
+
+## Find lab resource classes {#resource_classes}
+The first step is to find the lab resource classes that you want to use in your lab. The 
+[PythonLab](https://gitlab.com/OpenLabAutomation/lab-automation-packages/pythonLab) package provides a set
+of predefined resource classes (see [PythonLab api reference](pythonlab/api_reference.md)) that you can use as a starting 
+point.
+
+## Find or implement lab SiLA servers {#sila_servers}
+The default method for communicating with lab devices in the LARA lab automation suite is through SiLA servers. 
+[SiLA](https://sila-standard.com/) is an open source standard for communication between lab devices and has an active
+community of developers and users. SiLA server implementations for common lab devices can be found in various repositories,
+some of which we link to below:
+
+- [LARA Lab Automation device integration](https://gitlab.com/OpenLabAutomation/device-integration)
+- [SiLA Awesome List of Servers](https://gitlab.com/SiLA2/sila_awesome#servers)
+
+
+## Write your device wrappers {#device_wrappers}
+The communication between the lab orchestrator and the sila servers is handled by device wrappers. These wrappers 
+translate the high-level commands defined in the process descriptions to specific SiLA commands. The 
+[quickstart](quickstart.md) example comes with a couple of example wrappers that you can use as a starting point. 
+You can find more information about writing device wrappers in the [wrappers documentation](wrappers.md).
+
+## Configure your lab definition {#lab_definition}
+Your lab config file describes the available resources in your lab and their capacities. In the quickstart template this
+file is named `platform_config.yaml`. You will need to modify this file to match the resources available in your lab.
+More information about the lab definition can be found at [lab configuration](lab configuration.md).
+
+## Write your process descriptions {#process_descriptions}
+A Pythonlab process description describes the steps that should be executed in the lab. They are written in python and
+parsed into a workflow graph by the orchestrator. The process descriptions are the main part of your lab automation and 
+you will need to write them to match your specific use case. You can find more information about writing process 
+descriptions in the [pythonLab introduction](pythonlab/processes.md).
+
+## Customize the robot arm {#robot_arm}
+Customizing the robot arm involves two parts. First of all, you will need to configure the 
+[GenericRobotArm](https://gitlab.com/OpenLabAutomation/device-integration/genericroboticarm) SiLA server to match the 
+brand and model of your robot arm. 
+The [adaptation guide for the GenericRoboticArm](https://gitlab.com/OpenLabAutomation/device-integration/genericroboticarm/-/blob/main/docs/adaption.md)
+provides some guidance on how to do this.
+
+The second part is to configure locations of your labware and the devices with respect to the robot arm.
+This is done with the RobotTeachingService endpoint on the GenericRobotArm SiLA server. 
+
+More info on configuring the arm and the locations can be found in the [robot arm documentation](robot arm.md).

docs/lab configuration.md

@@ -0,0 +1,32 @@
+## Resources
+
+### ServiceResources
+
+
+::: pythonlab.resources.services.analysis.PlateReaderServiceResource
+
+
+::: pythonlab.resources.services.labware_storage.LabwareStorageResource
+
+
+::: pythonlab.resources.services.labware_storage.LabwareStorageResourcePool
+
+
+::: pythonlab.resources.services.incubation.IncubatorServiceResource
+
+
+::: pythonlab.resources.services.incubation.IncubatorServiceResourcePool
+
+
+::: pythonlab.resources.services.moving.MoverServiceResource
+
+
+::: pythonlab.resources.services.centrifugation.CentrifugeServiceResource
+
+
+
+### LabwareResources
+
+
+::: pythonlab.resource.DynamicLabwareResource
+

docs/pythonlab/api_reference.md

@@ -1,7 +1,8 @@
 # Quickstart
 ## Simulated example
 The fastest way to try out the LARA suite is by running the simulated example provided by the 
-[adaptation template](https://gitlab.com/OpenLabAutomation/adaption-template).
+[adaptation template](https://gitlab.com/OpenLabAutomation/adaption-template). After the adaptation is set up, you can start customizing it to your needs by following the 
+instructions in the [customization guide](customization.md).
 
 There are two ways to run the example: using Docker or running it directly with Python.
 

docs/pythonlab.md docs/pythonlab/introduction.mddocs/pythonlab.md renamed to docs/pythonlab/introduction.md

@@ -1,6 +1,6 @@
 # Wrappers
 Wrappers are the interface between the lab orchestrator and the actual devices. They translate the high-level commands
-defined in ?? to specific SILA commands.
+defined in PythonLab to specific SILA commands.
 
 ## The wrapper structure
 
@@ -19,8 +19,6 @@ class MyWrapper(DeviceInterface):
 ### ProcessStep
 Describes the step that should be executed.
 
-hoi
-bla
 
 ### ContainerInfo
 Describes the container that is handled

docs/pythonlab/processes.md

@@ -0,0 +1,43 @@
+from pythonlab.resources.services import *
+from pythonlab.resources import LabwareResource
+from pythonlab.resource import ServiceResource
+import jinja2
+from pathlib import Path
+
+
+template_dir = Path("./templates")
+output_dir = Path("./docs/pythonlab")
+
+
+def get_all_subclasses(cls):
+    """Recursively get all subclasses of a class."""
+    all_subclasses = []
+    for subclass in cls.__subclasses__():
+        all_subclasses.append(subclass)
+        all_subclasses.extend(get_all_subclasses(subclass))
+    return all_subclasses
+
+
+def main():
+    # Get all subclasses
+    service_subclasses = get_all_subclasses(ServiceResource)
+    labware_subclasses = get_all_subclasses(LabwareResource)
+
+    # Set up Jinja2 environment
+    env = jinja2.Environment(loader=jinja2.FileSystemLoader(template_dir))
+    template = env.get_template('api_reference.md.jinja2')
+
+    # Render template
+    output = template.render(
+        service_subclasses=service_subclasses,
+        labware_subclasses=labware_subclasses
+    )
+
+    # Write output file
+    output_file = output_dir / "api_reference.md"
+    output_file.write_text(output)
+    print(f"Generated {output_file}")
+
+
+if __name__ == "__main__":
+    main()

docs/quickstart.md

@@ -41,5 +41,14 @@ theme:
 plugins:
   - search
   - mermaid2
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_source: false
+            show_root_heading: true
+            show_root_full_path: true
+            docstring_style: sphinx
+
   - panzoom:
       full_screen: true