feat: docs cleanup (#351)

## changes

- [x] remove references to workstations (in installation)
- [x] remove references to workstations (in config)
- [x] remove references to workstations (in auth)
- [x] getting started > input data has some weird formatting 
- [x] docking > get results removed, get_poses 
- [x] docking > scatter plot of all poses 
- [x] docking > show composite job widget 
- [x] docking > composite job widget is animated 
- [x] abfe > update job widget 
- [x] abfe > job control section needs to be moved elsewhere (how to >
job control)
- [x] abfe > view trajectories 
- [x] complex preparation params (padding)
- [x] add a warning about loop modelling (in development)
- [x] protein > discourage saving to pdb in common use cases
- [x] ligandset > update display (no longer shows a dataframe)
- [ ] ligandset > add warning about konnektor 
- [ ] find pockets > add info about each pokcet and inspecting pocket
data
- [ ] find pockets > add info about making pockets from other sources 
- [ ] dock ligands > add ligandset widget showing poses
- [ ] dock ligands > add warning about constrained docking 
- [ ] filter outputs of docking --> needs a total overhaul
- [ ] job control -- needs to be updated with JobList
- [ ] clarify which methods modify state in Ligand or Protein
- [ ] clarify how we can get the org key from the UI
- [ ] docking > residue ID 
- [ ] add a "concepts" page

Author: sg-s

docs/configure.md

@@ -1,19 +1,12 @@
 # Configuration
 
-## On a Deep Origin workstation
-
-On a Deep Origin workstation, no configuration is needed! Within a workstation, the Deep Origin Python client is automatically configured.
-
-## On your local computer
-
-To run this package outside of a Deep Origin workstation (for example, on your own computer), first you need to configure this package. After installing this package, set your organization key and environment.
-
+To configure the client to connect to the DeepOrigin API, set your organization key and environment.
 
 
 ```{.python notest}
 from deeporigin import config
 config.set_value("org_key", "your-org-key")
-config.set_value("env", "prod")  # or "staging" / "edge"
+config.set_value("env", "prod")  
 ```
 
 

docs/dd/how-to/complex.md

@@ -1,4 +1,5 @@
-This document describes how to create a `Complex` object, that can be used to run Docking, ABFE and RBFE. 
+This document describes how to create a `Complex` object, that can be used to run [Docking](./docking.md), [ABFE](../tutorial/abfe.md) and [RBFE](../tutorial/rbfe.md).
+
 
 
 ## Creating a Complex
@@ -19,7 +20,7 @@ The directory should contain:
 
 ### From `Protein` and `Ligand` objects
 
-A `Complex` object can be also be constructed using `Protein` and `Ligand` objects. 
+A `Complex` object can be also be constructed using [`Protein`](./proteins.md) and [`Ligand`](./ligands.md) objects. 
 
 ```{.python notest}
 from deeporigin.drug_discovery import Complex, BRD_DATA_DIR, Protein, Ligand
@@ -33,7 +34,7 @@ sim = Complex(protein=protein, ligands=[ligand])
 ### From `LigandSet` objects
 
 
-A `Complex` object can also be constructed using `Protein` and `LigandSet` objects. 
+A `Complex` object can also be constructed using [`Protein`](./proteins.md) and [`LigandSet`](./ligands.md) objects. 
 
 ```{.python notest}
 from deeporigin.drug_discovery import Complex, BRD_DATA_DIR, Protein, LigandSet
@@ -70,12 +71,12 @@ sim.ligands = ligand5  # Replace with a single ligand
 ```
 
 ??? tip "Constructing Ligands"
-    To see how to construct Ligands, see [this](./ligands.md)
+    To see how to construct Ligands, see [:material-page-previous: Ligands](./ligands.md)
 
 ??? tip "Constructing the Protein"
-    To see how to construct the Protein, see [this](./proteins.md)
+    To see how to construct the Protein, see [:material-page-previous: Proteins](./proteins.md)
 
-## Preparing a complex
+## Preparing a Complex
 
 To prepare a protein-ligand complex for simulation or further analysis, use the `Complex.prepare()` method. This method runs system preparation on a given ligand in the context of the complex's protein, handling tasks such as protonation, water retention, and box padding.
 
@@ -84,7 +85,8 @@ To prepare a protein-ligand complex for simulation or further analysis, use the
 Typically, you would call this method using a ligand in the complex:
 
 ```{.python notest}
-sim.prepare(sim.ligands[0])
+prepared_system = sim.prepare(sim.ligands[0])
+prepared_system.show()
 ```
 
 You should see something like:
@@ -98,3 +100,19 @@ You should see something like:
 ></iframe>
 
 which shows you the prepared system.
+
+!!! info "System preparation parameters"
+    Look at the [:material-page-next: reference documentation](../ref/complex.md#src.drug_discovery.complex.Complex.prepare) to understand parameters for system preparation.
+
+
+## Specifying a Client
+
+A `Complex` can be configured with a [`DeepOriginClient`](../../platform/index.md) explicitly, using:
+
+```{.python notest}
+sim = Complex.from_dir(..., client=client)
+```
+
+## Reference
+
+-  [:material-page-next: Complex](../ref/complex.md)

docs/dd/how-to/ligands.md

@@ -138,21 +138,9 @@ ligand = Ligand.from_rdkit_mol(
 )
 ```
 
-This is particularly useful when you're working with RDKit's molecular manipulation functions and want to convert the results into a Deep Origin Ligand object for further processing or visualization.
+This is particularly useful when you're working with RDKit's molecular manipulation functions and want to convert the results into a `Ligand` for further processing or visualization.
 
 
-The method will:
-
-- Read the CSV file using pandas
-- Extract SMILES strings from the specified column
-- Create a Ligand instance for each valid SMILES
-- Store all other columns as properties in each Ligand instance
-- Skip any rows with empty or invalid SMILES strings
-
-!!! note "Error Handling"
-    The method will raise:
-    - `FileNotFoundError` if the CSV file does not exist
-    - `ValueError` if the specified SMILES column is not found in the CSV file
 
 ### From a CSV file
 
@@ -167,13 +155,27 @@ ligands = LigandSet.from_csv(
 )
 ```
 
+
+The method will:
+
+- Read the CSV file using pandas
+- Extract SMILES strings from the specified column
+- Create a Ligand instance for each valid SMILES
+- Store all other columns as properties in each Ligand instance
+- Skip any rows with empty or invalid SMILES strings
+
+!!! note "Error Handling"
+    The method will raise:
+    - `FileNotFoundError` if the CSV file does not exist
+    - `ValueError` if the specified SMILES column is not found in the CSV file
+
 ### Filtering Top Poses
 
 When working with docking results, you often have multiple poses for the same molecule. The `filter_top_poses()` method helps you select only the best pose for each unique molecule:
 
 ```{.python notest}
 
-# assuming poses comes from protein.dock()
+# assuming poses comes from protein.dock() or Complex.docking.get_results()
 
 # Filter to keep only the best pose per molecule (by binding energy)
 best_poses = poses.filter_top_poses()
@@ -217,29 +219,34 @@ A visualization similar to the following will be shown:
 
 A `LigandSet` can be visualized using several different methods. 
 
-#### Table view (2D)
+#### Summary card
 
-First, simply printing the `LigandSet` shows a table of ligands in the `LigandSet`:
+Simply inspecting the `LigandSet` object shows the following:
 
-```python
-from deeporigin.drug_discovery import LigandSet
+```{.python notest}
+ligands
+```
 
-smiles = {
-    "C/C=C/Cn1cc(-c2cccc(C(=O)N(C)C)c2)c2cc[nH]c2c1=O",
-    "C=CCCn1cc(-c2cccc(C(=O)N(C)C)c2)c2cc[nH]c2c1=O",
-}
 
-ligands = LigandSet.from_smiles(smiles)
-ligands
+<div style='width: 500px; padding: 15px; border: 1px solid #ddd; border-radius: 6px; background-color: #f9f9f9;'><h3 style='margin-top: 0; color: #333;'>LigandSet with 8 ligands</h3><p style='margin: 8px 0;'><strong>8</strong> unique SMILES</p><p style='margin: 8px 0;'>Properties: initial_smiles, r_exp_dg</p><div style='margin-top: 12px; padding-top: 12px; border-top: 1px solid #ddd;'><p style='margin: 4px 0; font-size: 0.9em; color: #666;'><em>Use <code>.to_dataframe()</code> to convert to a dataframe, <code>.show_df()</code> to view dataframewith structures, or <code>.show()</code> for 3D visualization</em></p></div></div>
+
+#### Table view (2D)
+
+To view a dataframe containined rendered (2D) structures of ligands, use:
 
+```python
+# for example
+from deeporigin.drug_discovery import LigandSet, DATA_DIR
+
+ligands = LigandSet.from_sdf(DATA_DIR / "ligands" / "ligands-brd-all.sdf")
+ligands.show_df()
 ```
 
 !!! success "Expected Output"
 
     ![](./../../images/ligands.png)
 
 
-This table view is also available using `ligands.show_df`
 
 #### Individual view (3D)
 
@@ -255,12 +262,12 @@ ligands.show()
 
 ```
 
-A visualization similar to this will be shown. Use the arrows to flip between ligands in the `LigandSet`. 
+A visualization similar to this will be shown. Use the arrows to switch between Ligands in the `LigandSet`. 
 
 <iframe 
     src="../../images/brd-3d.html" 
     width="100%" 
-    height="600" 
+    height="610" 
     style="border:none;"
     title="Visualization of ligands"
 ></iframe>

docs/dd/how-to/proteins.md

@@ -108,7 +108,7 @@ A visualization such as this will be shown:
 <iframe 
     src="../../images/1eby.html" 
     width="100%" 
-    height="600" 
+    height="610" 
     style="border:none;"
     title="Protein visualization"
 ></iframe>
@@ -143,6 +143,9 @@ ligand = protein.extract_ligand()
 
 ### Loop modelling 
 
+!!! warning "Coming soon"
+    Loop modelling functionality is under active development and will be available soon.
+
 Missing information and gaps in the structure can be filled in using the Loop Modelling tool. 
 
 For example, this protein from the PDB has missing elements, as can be seen from the dashed lines below:
@@ -157,7 +160,7 @@ protein.show()
 <iframe 
     src="../../images/5QSP.html" 
     width="100%" 
-    height="600" 
+    height="610" 
     style="border:none;"
     title="Protein visualization"
 ></iframe>
@@ -316,7 +319,7 @@ chains_ab = protein.select_chains(['A', 'B'])
 1. Always visualize the structure before and after preparation to ensure the desired changes were made
 2. When working with metalloproteins, use `remove_hetatm()` with appropriate `keep_resnames` or `remove_metals` parameters
 3. For multi-chain proteins, consider selecting specific chains before preparation
-4. Save the prepared structure using `to_pdb()` if you need to use it later:
+4. Save the prepared structure using `to_pdb()` if you need to use it outside of Deep Origin APIs.
 
 ```{.python notest}
 # Save the prepared structure
@@ -332,7 +335,6 @@ protein.to_pdb("prepared_protein.pdb")
 protein = Protein.from_pdb_id("1EBY")
 protein.remove_water()  # Remove water molecules
 protein.remove_hetatm(keep_resnames=['ZN'])  # Keep important cofactors
-protein.to_pdb("docking_ready.pdb")
 ```
 
 ### Working with Metalloproteins

docs/dd/ref/plots.md

@@ -61,6 +61,74 @@ scatter(
 )
 ```
 
+### Saving Plot to HTML File
+
+You can save the scatter plot to an HTML file instead of displaying it by providing the `output_file` parameter:
+
+```python
+import numpy as np
+from deeporigin.plots import scatter
+
+# Sample data
+x = np.array([1, 2, 3, 4, 5])
+y = np.array([2, 4, 6, 8, 10])
+smiles_list = [
+    "CCO",           # ethanol
+    "CC(=O)O",       # acetic acid
+    "c1ccccc1",      # benzene
+    "CCN(CC)CC",     # triethylamine
+    "CC(C)O"         # isopropanol
+]
+
+# Save scatter plot to HTML file
+scatter(
+    x=x, 
+    y=y, 
+    smiles_list=smiles_list, 
+    x_label="X Coordinate", 
+    y_label="Y Coordinate",
+    title="Molecule Analysis Plot",
+    output_file="scatter_plot.html"
+)
+```
+
+When `output_file` is provided, the plot is saved as an interactive HTML file that can be opened in any web browser. The file includes all interactive features such as hover tooltips with molecule images.
+
+### Setting Axis Limits
+
+You can control the axis limits using individual `x_lim_min`, `x_lim_max`, `y_lim_min`, and `y_lim_max` parameters. This gives you fine-grained control - you can set just the minimum, just the maximum, or both:
+
+```python
+import numpy as np
+from deeporigin.plots import scatter
+
+# Sample data
+x = np.array([1, 2, 3, 4, 5])
+y = np.array([2, 4, 6, 8, 10])
+smiles_list = [
+    "CCO",           # ethanol
+    "CC(=O)O",       # acetic acid
+    "c1ccccc1",      # benzene
+    "CCN(CC)CC",     # triethylamine
+    "CC(C)O"         # isopropanol
+]
+
+# Create scatter plot with custom axis limits
+scatter(
+    x=x, 
+    y=y, 
+    smiles_list=smiles_list, 
+    x_label="X Coordinate", 
+    y_label="Y Coordinate",
+    title="Molecule Analysis Plot",
+    x_lim_min=0,      # Set x-axis minimum to 0
+    x_lim_max=6,      # Set x-axis maximum to 6
+    y_lim_max=12      # Set only y-axis maximum to 12 (min auto-scales)
+)
+```
+
+Each limit parameter is optional and independent. If not provided, that limit will auto-scale based on the data range. This allows you to, for example, set only the maximum value for an axis while letting the minimum auto-scale.
+
 ## Features
 
 - **Interactive Hover**: Hover over any point to see the molecular structure image