ci: fixing docs deployment (#10)

.github/workflows/ci.yml

@@ -56,7 +56,7 @@ jobs:
         uses: actions/cache@v3
         with:
           path: ~/.local
-          key: poetry-1.1.12-0
+          key: poetry-1.4.0
 
       - name: Install and configure Poetry
         uses: snok/install-poetry@v1
@@ -77,13 +77,12 @@ jobs:
       # Install dependencies. `--no-root` means "install all dependencies but not the project
       # itself", which is what you want to avoid caching _your_ code. The `if` statement
       # ensures this only runs on a cache miss.
-      - run: poetry install --no-interaction --no-root
+      - run: poetry install --no-interaction --no-root --with docs
         if: steps.cache-deps.outputs.cache-hit != 'true'
 
       - run: poetry install --no-interaction --with docs
 
       - name: test
-
         run: |
           poetry run pytest --cov=pydango --cov-report=xml:coverage.xml --junitxml=test-results/test-results.xml tests
 
@@ -133,7 +132,7 @@ jobs:
         uses: actions/cache@v3
         with:
           path: ~/.local
-          key: poetry-1.1.12-0
+          key: poetry-1.4.0
 
       - name: Install and configure Poetry
         uses: snok/install-poetry@v1
@@ -157,7 +156,7 @@ jobs:
           restore-keys: |
             mkdocs-material-
 
-      - run: poetry run mkdocs gh-deploy --force
+      - run: .venv/bin/mkdocs gh-deploy --force
       - run: |
           poetry build
 

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 ### Chore
 
-* chore: fix pyproject.toml (#5) ([`e9063ff`](https://github.com/nadobando/pydangorm/commit/e9063ff034e4042d778b992aff2c55191d416fa9))
+- chore: fix pyproject.toml (#5) ([`e9063ff`](https://github.com/nadobando/pydangorm/commit/e9063ff034e4042d778b992aff2c55191d416fa9))
 
 ### Feature
 

README.md

@@ -17,6 +17,8 @@
 
 - **Asynchronous Support**: Perform asynchronous database operations for optimized I/O-bound tasks.
 
+### [Full Documentation](https://nadobando.github.io/pydangorm)
+
 ## Installation
 
 ```shell

docs/orm/base.md

@@ -1,4 +1,4 @@
-## BaseArangoModel Class Documentation
+## **`BaseArangoModel`**
 
 ### Overview
 
@@ -21,32 +21,9 @@ entities. It provides core attributes, methods, and configurations to facilitate
 
 ### Methods
 
-1. \*\*__init__(self, **data: Any)**: Initializes the model. If session data is provided, it sets the `__session__`
-   attribute, linking the model to a specific session.
-
-1. **\_decompose_class(cls, obj: Any)**: Decomposes or serializes the model. Customized to handle the specific needs of
-   ArangoDB entities.
-
-1. **\_calculate_keys(self, ...)**: Determines the keys for the model based on inclusion, exclusion, and other criteria.
-
-1. **from_orm(cls, obj: Any, session=None)**: Constructs a model instance from an ORM object. Handles relationships and
-   ensures that associated entities are correctly initialized.
-
-1. \*\*update_forward_refs(cls, **localns: Any)**: Resolves and updates forward references in relationships and fields.
-
 1. **save_dict(self)**: An abstract method to be implemented in derived classes. It outlines how the model data should
    be saved or serialized.
 
-### Tips for Developers:
-
-1. When creating a new model, consider extending the `BaseArangoModel`. It offers foundational attributes and methods
-   tailored for ArangoDB.
-1. Always specify relationships correctly. The `__relationships__` and `__relationships_fields__` attributes are central
-   to the model's operation.
-1. If working with forward references, ensure to call the `update_forward_refs` method after all models are defined to
-   resolve and set up relationships.
-1. Implement the `save_dict` method in derived classes to customize data saving or serialization behavior.
-
 ______________________________________________________________________
 
 This documentation offers a developer-centric guide to the `BaseArangoModel` class. It is designed to help developers

docs/orm/query.md

@@ -0,0 +1,46 @@
+## **`query.py`**
+
+The module within the orm sub-package provides functionalities and structures for ORM-based querying in
+relation to ArangoDB.
+It integrates with various parts of the ORM and aids in constructing and executing queries.
+
+#### Key Features
+
+- Automatic binding
+- `AQL` injection protection
+- query building
+
+## **`ORMQuery`**
+
+The `ORMQuery` class is a subclass of `AQLQuery`.
+It provides a Pythonic API for constructing queries for ArangoDB.
+
+## builder helpers
+
+### `for_()`
+
+the `for_()` method is used to specify the target vertex/edge collection of the query.
+
+```python
+from pydango.orm import for_
+
+
+for_(User).filter(User.name == "John Doe").return_(User)
+```
+
+### `traverse()`
+
+```python
+from pydango.orm import traverse
+from pydango.query.expressions import IteratorExpression
+from pydango.query import TraversalDirection
+
+edge = IteratorExpression()
+traverse(
+    (User, edge),
+    edges={"friends"},
+    start="people/1",
+    depth=(0, 1),
+    direction=TraversalDirection.OUTBOUND,
+).filter(User.name == "John Doe").return_(User)
+```

docs/query/expressions.md

@@ -1,4 +1,4 @@
-# Expressions
+# **Expressions**
 
 ## **Basic Expressions**
 

docs/query/functions.md

@@ -1,4 +1,4 @@
-# Functions
+# **Functions**
 
 ## **Abstract Functions**
 

docs/query/options.md

@@ -1,4 +1,4 @@
-# Options
+# **Options**
 
 A Base class representing general AQL options.
 Some AQL Operations have options that can be passed to them. to configure how the operation is performed.

docs/query/query.md

@@ -1,12 +1,16 @@
-# Query
+# **Query**
 
-## **AQLQuery**
+The pydango/query package provides a comprehensive and Pythonic interface for constructing and executing queries on
+ArangoDB. It abstracts the complexities of direct AQL (ArangoDB Query Language) and offers a structured approach to
+build both simple and complex queries with ease.
 
-### **Introduction**
+### **AQLQuery**
+
+#### **Introduction**
 
 The `AQLQuery` class offers a flexible and Pythonic interface for constructing, managing, and preparing AQL queries. It provides methods corresponding to a variety of AQL operations, allowing users to create complex queries by chaining these operations together.
 
-### Class Attributes:
+#### Class Attributes:
 
 - `_ops`: A list of operations associated with the query.
 - `sep`: Specifies the separator between different parts of the query.
@@ -16,85 +20,85 @@ The `AQLQuery` class offers a flexible and Pythonic interface for constructing,
 - `parent`: Reference to a parent `AQLQuery`, if any.
 - `__is_modification_query__`: Boolean indicating if the query modifies data.
 
-### Methods:
+#### Methods:
 
-#### **`for_`**
+##### **`for_`**
 
 `for_(self, collection_or_variable, in_: Expression) -> 'AQLQuery'`
 Adds a [**`FOR`**](./operations.md#foroperation) operation to the query.  Iterates over a collection or variable.
 
-#### **`filter`**
+##### **`filter`**
 
 `filter(self, filter_expr: Expression) -> 'AQLQuery'`
 Adds a [**`FILTER`**](./operations.md#filteroperation) operation to the query. Filters the results of a query based on a condition.
 
-#### **`sort`**
+##### **`sort`**
 
 `sort(self, *args: Expression) -> 'AQLQuery'`
 Adds a [**`SORT`**](./operations.md#sortoperation) operation to the query. Sorts the results of a query based on provided parameters.
 
-#### **`let`**
+##### **`let`**
 
 `let(self, variable: Union[str, VariableExpression], value: Expression) -> Union[VariableExpression, 'AQLQuery']`
 Adds a [**`LET`**](./operations.md#letoperation) operation to the query. Defines a variable within the query.
 
-#### **`return_`**
+##### **`return_`**
 
 `return_(self, return_expr: Expression) -> 'AQLQuery'`
 Adds a [**`RETURN`**](./operations.md#returnoperation) operation to the query. Specifies the return value of the query.
 
-#### **`limit`**
+##### **`limit`**
 
 `limit(self, limit: int, offset: Optional[int] = None) -> 'AQLQuery'`
 Adds a [**`LIMIT`**](./operations.md#limitoperation) operation to the query. Limits the number of results returned by the query.
 
-#### **`insert`**
+##### **`insert`**
 
 `insert(self, doc: Dict[str, Any], collection: str) -> 'AQLQuery'`
 Adds an [**`INSERT`**](./operations.md#insertoperation) operation to the query. Inserts a document into a collection.
 
-#### **`remove`**
+##### **`remove`**
 
 `remove(...) -> 'AQLQuery'`
 Adds a [**`REMOVE`**](./operations.md#removeoperation) operation to the query. Removes documents from a collection.
 
-#### **`update`**
+##### **`update`**
 
 `update(...) -> 'AQLQuery'`
 Adds an [**`UPDATE`**](./operations.md#updateoperation) operation to the query. Updates documents in a collection.
 
-#### **`replace`**
+##### **`replace`**
 
 `replace(...) -> 'AQLQuery'`
 Adds a [**`REPLACE`**](./operations.md#replaceoperation) operation to the query. Replaces documents in a collection.
 
-#### **`upsert`**
+##### **`upsert`**
 
 `upsert(...) -> 'AQLQuery'`
 Adds an [**`UPSERT`**](./operations.md#upsertoperation) operation to the query. Inserts or updates documents in a collection.
 
-#### **`collect`**
+##### **`collect`**
 
 `collect(...) -> 'AQLQuery'`
 Adds a [**`COLLECT`**](./operations.md#collectoperation) operation to the query. Collects documents from a collection.
 
-#### **`traverse`**
+##### **`traverse`**
 
 `traverse(...) -> 'AQLQuery'`
 Creates a [**`TRAVERSE`**](./operations.md#traverseoperation) operation. Traverses a graph.
 
-#### **`prepare`**
+##### **`prepare`**
 
 `prepare() -> PreparedQuery`
 Prepares the query for execution, returning a `PreparedQuery` instance.
 
-## **PreparedQuery**
+### **PreparedQuery**
 
-### Introduction
+#### Introduction
 
 The PreparedQuery class represents a prepared AQL query ready for execution against an ArangoDB instance. It encapsulates the AQL query string and any bind variables that need to be provided alongside the query.
 
-### Class Attributes:
+#### Class Attributes:
 
 - **`query`**: A string that holds the AQL query.
 - **`bind_vars`**: A dictionary of variables to be bound to the query. These are represented in a JSON-compatible format.

docs/query/usage.md

@@ -1,4 +1,4 @@
-## AQLQuery Usage
+## **AQLQuery**
 
 ### 1. Simple Query to Fetch Data
 

docs/quickstart.md

@@ -95,9 +95,9 @@ async def async_application():
 Construct and execute a simple query to retrieve all people over the age of 25:
 
 ```python
-from pydango.query import ORMQuery
+from pydango.orm import for_
 
-query = ORMQuery().for_(Person).filter(Person.age > 25).return_(Person)
+query = for_(Person).filter(Person.age > 25).return_(Person)
 people_over_25 = await session.execute(query)
 ```
 
@@ -106,17 +106,14 @@ people_over_25 = await session.execute(query)
 Construct and execute a simple query to cities visited by people who visited the same cities of a person:
 
 ```python
-from pydango import ORMQuery, TraversalDirection
-
-person_visited_cities = (
-    ORMQuery()
-    .traverse(
-        Person,
-        edges=[Person.visited],
-        start=person.id,
-        depth=(1, 2),
-        direction=TraversalDirection.INBOUND,
-    )
-    .return_(Person)
-)
+from pydango.orm import traverse
+from pydango import TraversalDirection
+
+person_visited_cities = traverse(
+    Person,
+    edges=[Person.visited],
+    start=person.id,
+    depth=(1, 2),
+    direction=TraversalDirection.INBOUND,
+).return_(Person)
 ```

mkdocs.yml

@@ -22,21 +22,29 @@ theme:
 nav:
   - Home: index.md
   - Installation: installation.md
-  - Quick Start: quickstart.md
+  - Tutorial: quickstart.md
   - Documentation:
-      Vertex: orm/vertex.md
-      Edge: orm/edge.md
-      Collection Config: orm/collection.md
-      Query: orm/query.md
-      Session: session.md
+      - Vertex: orm/vertex.md
+      - Edge: orm/edge.md
+      - Collection Config: orm/collection.md
+      - Query: orm/query.md
+      - Session: session.md
   - API:
-      Query Core (Low Level):
-        Usage: query/usage.md
-        Expressions: query/expressions.md
-        Functions: query/functions.md
-        Options: query/options.md
-        Operations: query/operations.md
-        Query: query/query.md
+      - ORM:
+          - Base: orm/base.md
+
+#        - Vertex: api/orm/vertex.md
+#        - Edge: api/orm/edge.md
+#        - Collection Config: api/orm/collection.md
+#        - Query: api/orm/query.md
+#        - Session: api/session.md
+      - Query Core (Low Level):
+          - Usage: query/usage.md
+          - Expressions: query/expressions.md
+          - Functions: query/functions.md
+          - Options: query/options.md
+          - Operations: query/operations.md
+          - Query: query/query.md
 
 repo_url: https://github.com/nadobando/pydangorm
 repo_name: nadobando/pydangorm