docs: add docs for first users of this package (metabolomics team)

Author: ecarrenolozano

README.md

@@ -153,6 +153,3 @@ Please make sure to update tests as appropriate.
 ## License
 
 [MIT](https://choosealicense.com/licenses/mit/)
-
-- [ ] TODO: Modify this based on the license you choose.
-- [ ] TODO: Modify the LICENSE file based on the license you choose.

docs/about.md

@@ -1,3 +1,3 @@
 # About
 
-This project was created by Edwin Carreño.
+This project was created by Saezlab and Scientifc Software Center.

docs/assets/isometric_logo.png

@@ -1,3 +1,58 @@
-# Welcome to OntoGraph Package
+# Welcome to OntoGraph
 
-This is the main documentation page.
+![Image title](assets/project-banner-readme.png){ align=center }
+
+**OntoGraph** is a Python package for programmatic access, navigation, and analysis of biomedical ontologies. It provides a unified interface to download, load, and query ontologies from the [OBO Foundry](https://obofoundry.org/) and other sources, supporting both OBO and OWL formats.
+
+---
+
+## Key Features
+
+- **Ontology Catalog Access**  
+  Browse and retrieve metadata for hundreds of ontologies from the OBO Foundry registry.
+
+- **Flexible Ontology Loading**  
+  Load ontologies from local files, remote URLs, or directly from the OBO Foundry catalog.
+
+- **Graph Navigation & Querying**  
+  Traverse ontology graphs: get parents, children, ancestors, descendants, siblings, and roots of terms.
+
+- **Relationship Analysis**  
+  Check ancestor/descendant/sibling relationships, find common and lowest common ancestors, and compute distances between terms.
+
+- **Introspection Utilities**  
+  Analyze ontology structure, calculate paths and trajectories, and visualize term hierarchies.
+
+- **Caching & Download Management**  
+  Efficiently download and cache ontology files for offline use.
+
+---
+
+## Main Components
+
+- **ClientCatalog**  
+  Interact with the ontology catalog: list available ontologies, retrieve metadata, and explore catalog structure.
+
+- **ClientOntology**  
+  Load and query individual ontologies: navigate term relationships, analyze graph structure, and perform advanced queries.
+
+- **Loader & Downloader Modules**  
+  Abstract and concrete classes for loading ontologies and managing downloads from various sources.
+
+- **Query Adapters**  
+  Modular classes for navigation (`OntologyNavigator`), relationship analysis (`OntologyRelations`), and introspection (`OntologyIntrospection`).
+
+---
+
+## Why OntoGraph?
+
+- Unified and extensible API for ontology operations
+- Designed for both interactive exploration and programmatic workflows
+- Built-in support for caching and efficient data management
+- Modular architecture for easy integration and extension
+
+---
+
+> _Explore, analyze, and integrate ontologies with ease using OntoGraph!_
+
+---

docs/assets/logo_ontograph.png

@@ -1,37 +1,48 @@
 # Installation guide
 
-We strongly recommend installing a few prerequisites to ensure a smooth experience. These prerequisites are:
+## Prerequisites
+
+Before installing `ontograph`, please ensure you have the following tools installed:
+
+
+| Tool   | Minimum Version | Description                           | Installation Guide                                                           |
+| ------ | --------------- | ------------------------------------- | ---------------------------------------------------------------------------- |
+| Python | 3.10            | Programming language                  | [Install Python 3](https://docs.python.org/3/using/index.html)               |
+| uv     | —               | Python packaging & dependency manager | [Install uv](https://docs.astral.sh/uv/getting-started/installation/)        |
+| git    | —               | Version control system                | [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) |
 
-1. *Python 3* (version >= 3.10)
-      - [Install Python 3](https://docs.python.org/3/using/index.html)
-2. *Poetry* (Python packaging and dependency manager)
-      - [Install Poetry](https://python-poetry.org/docs/#installation)
-3. *git* (version control manager)
-      - [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
-4. *Docker* (containerization technology) [optional]
-      - [Install Docker](https://docs.docker.com/engine/)
 
 !!! tip "Tip"
     If you are missing any of those pre-requisites, **please follow the installation guide in each resource before you continue**.
 
 
 ## Checking prerequisites
 
-You can verify access to these components in your terminal:
+Verify that everything is installed by running:
 
-1. `Python` version 3.10 or higher.
-   ```bash
-   python --version
-   ```
-2. `Poetry`
+```bash
+python --version   # Should be 3.10 or higher
+uv --version
+git --version
+```
+
+## Installation
+
+This package is currently under development. To try it out, you can clone the repository and install it in "editable" mode. This allows you to make changes to the code and have them reflected immediately without reinstalling.
+
+1. **Clone the repository:**
    ```bash
-   poetry --version
+   git clone https://github.com/saezlab/ontograph.git
    ```
-3. `git`
+
+2. **Navigate into the project directory:**
    ```bash
-   git --version
+   cd ontograph
    ```
-4. `Docker`
+
+3. **Install the package in editable mode using `uv`:**
    ```bash
-   docker --version
+   uv pip install -e .
    ```
+
+You can now start using `ontograph` in your Python environment. Any changes you make to the source code will take effect immediately.

docs/assets/project-banner-readme.png

@@ -0,0 +1,189 @@
+# Quickstart
+
+Welcome to the OntoGraph Quickstart!  
+This guide will help you get up and running with OntoGraph, showing you how to explore ontology catalogs and interact with ontologies programmatically.
+
+---
+
+## 1. Explore the OBO Foundry Catalog
+
+First, let's interact with the OBO Foundry catalog to discover available ontologies.
+
+```python
+from ontograph.client import ClientCatalog
+
+# Create a catalog client (specify a cache directory for downloads)
+client_catalog = ClientCatalog(cache_dir="./data/out")
+
+# Load the catalog (downloads if not cached)
+client_catalog.load_catalog()
+```
+
+### List Available Ontologies
+
+```python
+# Get a list of ontologies (as dicts with id and title)
+ontologies_list = client_catalog.list_available_ontologies()
+print(ontologies_list[:3])  # Show the first three
+```
+
+### Print Ontology List
+
+```python
+client_catalog.print_available_ontologies()
+```
+
+### Get Metadata for a Specific Ontology
+
+```python
+# Show metadata for the Gene Ontology (GO)
+metadata_go = client_catalog.get_ontology_metadata(ontology_id="go", show_metadata=True)
+```
+
+---
+
+## 2. Load and Explore an Ontology
+
+Now, let's load an ontology and explore its structure.
+
+```python
+from ontograph.client import ClientOntology
+
+# Create an ontology client
+client_ontology = ClientOntology(cache_dir="./data/out")
+
+# Load a sample ontology (provided in the repo for testing)
+client_ontology.load(file_path_ontology="./tests/resources/dummy_ontology.obo")
+```
+
+---
+
+## 3. Visualize the Ontology Structure
+
+The included demo ontology has the following structure (Z is the root):
+
+```mermaid
+graph TB
+    Z((Z)) --> A((A))
+    Z((Z)) --> B((B))
+    Z((Z)) --> C((C))
+    A((A)) --> D((D))
+    B((B)) --> H((H))
+    B((B)) --> I((I))
+    C((C)) --> J((J))
+    D((D)) --> E((E))
+    D((D)) --> F((F))
+    D((D)) --> G((G))
+    H((H)) --> K((K))
+    I((I)) --> L((L))
+    J((J)) --> M((M))
+    E((E)) --> N((N))
+    F((F)) --> O((O))
+    F((F)) --> Y((Y))
+    G((G)) --> K1((K1))
+    G((G)) --> K2((K2))
+    K((K)) --> Q((Q))
+    K((K)) --> G1((G))
+    M((M)) --> S((S))
+    G1((G)) --> K11((K1))
+    G1((G)) --> K21((K2))
+    S((S)) --> T((T))
+    T((T)) --> U((U))
+    U((T)) --> V((V))
+    U((U)) --> W((W))
+    W((W)) --> Y1((Y))
+```
+
+---
+
+## 4. Common Ontology Queries
+
+### Navigation
+
+- **Get ancestors:**  
+  ```python
+  client_ontology.get_ancestors(term_id="S")
+  ```
+- **Ancestors with distance:**  
+  ```python
+  list(client_ontology.get_ancestors_with_distance(term_id="S"))
+  ```
+- **Get children:**  
+  ```python
+  client_ontology.get_children(term_id="A")
+  ```
+- **Get descendants:**  
+  ```python
+  client_ontology.get_descendants(term_id="U")
+  ```
+- **Descendants with distance:**  
+  ```python
+  list(client_ontology.get_descendants_with_distance(term_id="U"))
+  ```
+- **Get parents:**  
+  ```python
+  client_ontology.get_parents(term_id="U")
+  ```
+- **Get root node:**  
+  ```python
+  client_ontology.get_root()
+  ```
+- **Get siblings:**  
+  ```python
+  client_ontology.get_siblings(term_id="K1")
+  ```
+- **Get a term:**  
+  ```python
+  client_ontology.get_term(term_id="E")
+  ```
+
+### Relations
+
+- **Common ancestors:**  
+  ```python
+  client_ontology.get_common_ancestors(node_ids=["K", "L"])
+  ```
+- **Lowest common ancestors:**  
+  ```python
+  client_ontology.get_lowest_common_ancestors(node_ids=["K", "L"])
+  ```
+- **Is ancestor:**  
+  ```python
+  client_ontology.is_ancestor(ancestor_node="A", descendant_node="N")
+  ```
+- **Is descendant:**  
+  ```python
+  client_ontology.is_descendant(descendant_node="A", ancestor_node="N")
+  ```
+- **Is sibling:**  
+  ```python
+  client_ontology.is_sibling(nodeA="F", nodeB="G")
+  ```
+
+### Introspection
+
+- **Distance from root:**  
+  ```python
+  client_ontology.get_distance_from_root(term_id="V")
+  ```
+- **Path between nodes:**  
+  ```python
+  client_ontology.get_path_between(nodeA="Q", nodeB="B")
+  ```
+- **All trajectories from root:**  
+  ```python
+  trajectories = client_ontology.get_trajectories_from_root(term_id="Y")
+  ```
+- **Print trajectories tree:**  
+  ```python
+  client_ontology.print_term_trajectories_tree(trajectories)
+  ```
+
+---
+
+## Next Steps
+
+- Explore the [API Reference](../../reference/source/ontograph/client-ontology.md) for more details.
+- Try loading your own ontology files or experiment with different queries!
+
+> _OntoGraph makes ontology exploration and analysis simple and powerful.

docs/index.md

@@ -0,0 +1,28 @@
+# ClientCatalog
+
+`ClientCatalog` is the main interface for interacting with the ontology catalog in OntoGraph.  
+It allows you to load the catalog, list available ontologies, retrieve metadata, and access download URLs and formats.
+
+This class is ideal for users who want to explore the catalog of available ontologies, inspect their metadata, and prepare for ontology loading and analysis.
+
+---
+
+## Features
+
+- Load and cache the ontology catalog from [OBO Foundry](https://obofoundry.org/)
+- List all available ontologies and their metadata
+- Retrieve metadata for a specific ontology
+- Get download URLs and available formats for each ontology
+- Print the catalog schema tree for exploration
+
+---
+
+## API Reference
+
+::: ontograph.client.ClientCatalog
+
+---
+
+## See Also
+
+- [ClientOntology](client-ontology.md): For loading and querying individual ontologies.