Updates and fixes, enhanced docs

docs/api.md

@@ -13,7 +13,7 @@ This page provides API docs for the Python API of blast2galaxy.
       show_signature_annotations: false
 -->
 
-
+<!--
 ::: blast2galaxy.cli
     handler: python
     options:
@@ -22,3 +22,14 @@ This page provides API docs for the Python API of blast2galaxy.
       show_signature: true
       separate_signature: true
       show_signature_annotations: false
+-->
+
+
+::: blast2galaxy
+    handler: python
+    options:
+      show_source: false
+      annotations_path: brief
+      show_signature: true
+      separate_signature: true
+      show_signature_annotations: false

docs/cli.md

@@ -4,4 +4,6 @@ This page provides documentation for our command line tools.
 
 ::: mkdocs-click
     :module: blast2galaxy.cli
-    :command: cli
+    :command: cli
+    :style: plain
+    :list_subcommands: True

docs/configuration.md

@@ -1,5 +1,17 @@
 # Configuration
 
+blast2galaxy provides two ways to configure servers and profiles to be used with blast2galaxy.
+
+- **TOML file based configuration**<br />
+  This type of configuration can be used when using the CLI or Python API of blast2galaxy.
+
+- **Python API based configuration**<br />
+  This type of configuration can only be used when using the Python API of blast2galaxy.
+
+Both ways of configuration are described in the following sections of this page.
+
+## TOML file based configuration
+
 To connect to an API of an existing Galaxy server, the user of blast2galaxy has to provide API access credentials in the form of a Galaxy API key. Furthermore, it is possible to connect via the username and password of the user account on the specific Galaxy server. For security reasons, the latter variant should only be used if the use of an API key is not possible.
 
 
@@ -10,12 +22,16 @@ If it can't find a configuration file in the current working directory it looks
 If it can't find any configuration file an error message will be displayed.
 
 An individually named configuration file at a storage location of your choice can be set via the `--configfile=PATH` parameter of the CLI. 
-Example: `--configfile=/opt/myapps/config/app1.blast2galaxy.config.toml`
+
+Example: 
+```
+--configfile=/opt/myapps/config/app1.blast2galaxy.config.toml
+```
 
 
 
 <br />
-<h3>General Structure of the config TOML</h3>
+### General Structure of the config TOML file
 
 The configuration file has two types of sections:
 
@@ -28,7 +44,7 @@ Where `###` has to be replaced with either `default` or a unique server-ID / pro
 !!! note
 
     A config file must consist at least one `[servers.]` entry and one `[profiles.]` entry. 
-    If you provide `[servers.default]` and `[profiles.default]` the `--profile` parameter of the CLI can be omitted.
+    If you provide `[servers.default]` and `[profiles.default]` the `--server=` and `--profile=` parameter of the CLI commands can be omitted.
 
 
 
@@ -38,7 +54,7 @@ Where `###` has to be replaced with either `default` or a unique server-ID / pro
 
 
 <br />
-<h3>Servers</h3>
+### Servers
 
 The servers section holds one or multiple Galaxy server instances with their corresponding URLs and API-Keys.
 
@@ -52,28 +68,28 @@ api_key = "65dcb*******************************"
 
 !!! tip
 
-    After configuration of at least one default server you can use the `list-tools` command of the CLI to get a table with all NCBI BLAST+ tools and DIAMOND available on that Galaxy server. The table also contains the Tool-IDs for configuration of the profiles and also all available sequences databases corresponding to the specific tool.
+    After configuration of at least one default server you can use the `list-tools` command of the CLI to get a table with all compatible NCBI BLAST+ tools and DIAMOND available on that Galaxy server. The table also contains the Tool-IDs for configuration of the profiles.
 
     List all available tools of the default server:
     ```bash
     blast2galaxy list-tools
     ```
 
-    List all available tools of the server with ID <span style="font-family: monospace;">server_id</span>:
+    List all available tools of the server with ID `SERVER_ID`:
     ```bash
-    blast2galaxy list-tools --server=server_id
+    blast2galaxy list-tools --server=SERVER_ID
     ```
 
 
 <br />
-<h3>Profiles</h3>
+### Profiles
 
 The profiles section holds one or multiple profiles where each profile configures at least the Galaxy server and the Tool-ID to be used.
 
 Mandatory fields for each profile are:
 
 - `server` &nbsp; *An ID of an configured server in the servers section*
-- `tool_id` &nbsp; *Tool-ID for the tool on the Galaxy server*
+- `tool` &nbsp; *Tool-ID for the tool on the Galaxy server*
 
 Optional fields for each profile are:
 
@@ -84,10 +100,22 @@ Example:
 ```toml
 [profiles.default]
 server = "default"
-tool_id = "toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastn_wrapper/2.14.1+galaxy2"
+tool = "toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastn_wrapper/2.14.1+galaxy2"
 ```
 
+!!! tip
+
+    After configuration of at least one default profile you can use the `list-dbs` command of the CLI to get a table with all available sequence databases for a specific tool.
+
+    List all available databases of the tool with ID `TOOL_ID` on the default server:
+    ```bash
+    blast2galaxy list-tools --tool=TOOL_ID
+    ```
 
+    List all available databases of the tool with ID `TOOL_ID` on the server with ID `SERVER_ID`:
+    ```bash
+    blast2galaxy list-tools --server=SERVER_ID --tool=TOOL_ID
+    ```
 
 
 
@@ -105,24 +133,75 @@ api_key = "1k32z*******************************"
 
 [profiles.default]
 server = "default"
-tool_id = "toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastn_wrapper/2.14.1+galaxy2"
+tool = "toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastn_wrapper/2.14.1+galaxy2"
 
 [profiles.blastp]
 server = "default"
-tool_id = "toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastp_wrapper/2.14.1+galaxy2"
+tool = "toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastp_wrapper/2.14.1+galaxy2"
 
 [profiles.blastp_plantae_genes]
 server = "default"
-tool_id = "toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastp_wrapper/2.14.1+galaxy2"
+tool = "toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastp_wrapper/2.14.1+galaxy2"
 database = "plant_proteins"
 
 [profiles.diamond_blastp_plantae_genes]
 server = "default"
-tool_id = "toolshed.g2.bx.psu.edu/repos/bgruening/diamond/bg_diamond/2.0.15+galaxy0"
+tool = "toolshed.g2.bx.psu.edu/repos/bgruening/diamond/bg_diamond/2.0.15+galaxy0"
 database = "plant_proteins"
 
 [profiles.blastn_vertebrata]
 server = "default"
-tool_id = "toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastn_wrapper/2.14.1+galaxy2"
+tool = "toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastn_wrapper/2.14.1+galaxy2"
 database = "vertebrata_proteins"
+```
+
+## Python API based configuration
+
+If you use the Python API of blast2galaxy it is also possible to provide the configuration programmatically without the need for an `.blast2galaxy.toml` file.
+
+Example for API based configuration during runtime for setting a default server and a default profile:
+```python
+import blast2galaxy
+
+blast2galaxy.config.add_default_server(
+    server_url = 'https://usegalaxy.eu', 
+    api_key = 'your_api_key'
+)
+
+blast2galaxy.config.add_default_profile(
+    server = 'default', 
+    tool = 'toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastp_wrapper/2.14.1+galaxy2'
+)
+
+blast2galaxy.blastp(
+    query = 'prot.fasta',
+    db = 'database_id',
+    out = 'result_blastp.txt',
+    outfmt = '6'
+)
+```
+
+If you want to add further servers and profiles beside the defaults you can use `blast2galaxy.config.add_server()` and `blast2galaxy.config.add_profile()`:
+```python
+import blast2galaxy
+
+blast2galaxy.config.add_server(
+    server = 'myserver',
+    server_url = 'https://usegalaxy.eu', 
+    api_key = 'your_api_key'
+)
+
+blast2galaxy.config.add_profile(
+    profile = 'diamond',
+    server = 'myserver',
+    tool = 'toolshed.g2.bx.psu.edu/repos/bgruening/diamond/bg_diamond/2.0.15+galaxy0'
+)
+
+blast2galaxy.diamond(
+    profile = 'diamond',
+    query = 'prot.fasta',
+    db = 'database_id',
+    out = 'result_diamond_blastp.txt',
+    outfmt = '6'
+)
 ```

docs/index.md

@@ -1,16 +1,20 @@
-# Welcome to blast2galaxy
+# Welcome to blast2galaxy documentation
 
 blast2galaxy provides a Python API and CLI to perform BLAST and DIAMOND queries against Galaxy servers that have the NCBI BLAST+ tools [[1]](#1) and DIAMOND [[2]](#2) installed.
 
+blast2galaxy is available as a PyPI package (pip) and tested to be working with the following Python versions: 3.10, 3.11, 3.12
+
 
 ![Screenshot](figure_1_v3.png)
 
-*Figure 1: Blast2galaxy provides a high-level convenience layer between any Galaxy server with NCBI BLAST+ tools and/or DIAMOND installed and different types of clients and usage scenarios. Researchers, applications and computational pipelines can either use the Python-API or the CLI of blast2galaxy to send requests for a BLAST search to any compatible Galaxy server. The use of BLAST+ tools and/or DIAMOND by multiple applications and the provision of corresponding BLAST databases can be centralized and made reusable by use of a Galaxy server.*
+<small>*Figure 1: blast2galaxy provides a high-level convenience layer between any Galaxy server with NCBI BLAST+ tools and/or DIAMOND installed and different types of clients and usage scenarios. Researchers, applications and computational pipelines can either use the Python-API or the CLI of blast2galaxy to send requests for a BLAST search to any compatible Galaxy server. The use of BLAST+ tools and/or DIAMOND by multiple applications and the provision of corresponding BLAST databases can be centralized and made reusable by use of a Galaxy server.*</small>
+
 
 Please read the [CLI Reference](cli.md) if you want to use blast2galaxy on the command line as drop-in replacement for NCBI BLAST+ tools or DIAMOND
 or read the [API Reference](api.md) if you want to use blast2galaxy inside a Python application to perform BLAST or DIAMOND queries against a Galaxy server.
 
 
+
 <h2>References</h2>
 
 <a id="1">[1]</a> Peter J. A. Cock, John M. Chilton, Björn Grüning, James E. Johnson, Nicola Soranzo, NCBI BLAST+ integrated into Galaxy, GigaScience, Volume 4, Issue 1, December 2015, s13742-015-0080-7, [https://doi.org/10.1186/s13742-015-0080-7](https://doi.org/10.1186/s13742-015-0080-7)