From 8a833a5cf2eea0fbbeb44f834d7399e4ed466131 Mon Sep 17 00:00:00 2001
From: Sean <63349506+SerRichard@users.noreply.github.com>
Date: Tue, 9 Jul 2024 15:53:17 +0200
Subject: [PATCH] update docs (#53)

* update docs

* proof read
---
 docs/guide/auth.md | 14 ++++----
 docs/guide/orms.md | 79 +++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 85 insertions(+), 8 deletions(-)

diff --git a/docs/guide/auth.md b/docs/guide/auth.md
index 13486fc..bc073a6 100644
--- a/docs/guide/auth.md
+++ b/docs/guide/auth.md
@@ -6,15 +6,15 @@ The authentication function for this repo has been set using the predefined vali
 
 You can either inherit the authenticator class and overwrite the validate function, or provide an entirely new function. In either case, it's worth noting that the return value for any provided authentication function currently needs to be of type User. If you want to additionally change the return type you may have to overwrite the endpoint entirely.
 
-        client = OpenEOCore(
-            ...
-        )
+    client = OpenEOCore(
+        ...
+    )
 
-        api = OpenEOApi(client=client, app=FastAPI())
+    api = OpenEOApi(client=client, app=FastAPI())
 
-        def cool_new_auth():
-            return User(user_id=specific_uuid, oidc_sub="the-only-user")
+    def cool_new_auth():
+        return User(user_id=specific_uuid, oidc_sub="the-only-user")
 
-        core_api.override_authentication(cool_new_auth)
+    core_api.override_authentication(cool_new_auth)
 
 Now any endpoints that originally used the Authenticator.validate function, will now use cool_new_auth instead.
diff --git a/docs/guide/orms.md b/docs/guide/orms.md
index 65e1cbb..d519433 100644
--- a/docs/guide/orms.md
+++ b/docs/guide/orms.md
@@ -1 +1,78 @@
-## To be defined
\ No newline at end of file
+## Extending the Object Relational models.
+
+Currently it's possible to extend the object relational models that the api uses in order to support extra values a backend might want to includse in any EndpointRegisters.
+
+## How to extend the models.
+
+In order to effectively use the extended models, you need to update the models.py file found in the alembic directory. After updating the models.py file, you will need to manually update the endpoints where you would like the new model to be used. This is a current pain point, and it would be good to improve this in the future.
+
+#### Original - models.py
+
+    from openeo_fastapi.client.psql.settings import BASE
+    from openeo_fastapi.client.psql.models import *
+
+    metadata = BASE.metadata
+
+#### Updated - models.py
+
+
+    from typing import Optional
+    from openeo_fastapi.client.jobs import Job
+    from openeo_fastapi.client.psql.settings import BASE
+    from openeo_fastapi.client.psql.models import *
+
+    class ExtendedJobORM(JobORM):
+
+        special_string = Column(VARCHAR, nullable=True)
+        """A very special string."""
+
+
+    class ExtendedJob(Job):
+
+        special_string: Optional[str]
+        """A very special string."""
+
+        @classmethod
+        def get_orm(cls):
+            return ExtendedJobORM
+
+
+    metadata = BASE.metadata
+
+#### Using extended model
+
+In order use the class ExtendedJob, we will need to extend the register. The example below extends the JobRegister and edits the create_job function to create the ExtendedJob and includes setting the value for the new parameter. You will need to version the database in order for the new model to work, and additionally add the NewJobsRegister to the app instance [See Registers](/docs/guide/registers.md).
+
+    ...
+    from openeo_fastapi.client.jobs import JobsRegister
+    from openeo_argoworkflows_api.psql.models import ExtendedJob
+
+    class NewJobsRegister(JobsRegister):
+
+        def __init__(self, settings, links) -> None:
+            super().__init__(settings, links)
+
+
+        def create_job(
+            self, body: JobsRequest
+        ):
+            """Create a new ExtendedJob.
+            """
+
+            # Create the job
+            job = ExtendedJob(
+                job_id=job_id,
+                process=body.process,
+                status=Status.created,
+                title=body.title,
+                description=body.description,
+                user_id=user.user_id,
+                created=datetime.datetime.now(),
+                special_string="A new type of job."
+            )
+
+            engine.create(create_object=job)
+
+            return Response(
+                status_code=201,
+            )