[DOC] Add tutorial for adding your own objects (#368)

Co-authored-by: Philip Meier <github.pmeier@posteo.de>
Co-authored-by: Pavithra Eswaramoorthy <pavithraes@outlook.com>

Author: 3 people

docs/assets/images/ragna-tutorial-components.png

@@ -99,26 +99,7 @@ def answer(self, prompt, sources):
 
 rest_api = ragna_docs.RestApi()
 
-client = rest_api.start(config, authenticate=True)
-
-# %%
-# Upload the document.
-
-document_upload = (
-    client.post("/document", json={"name": document_path.name})
-    .raise_for_status()
-    .json()
-)
-
-document = document_upload["document"]
-
-parameters = document_upload["parameters"]
-client.request(
-    parameters["method"],
-    parameters["url"],
-    data=parameters["data"],
-    files={"file": open(document_path, "rb")},
-).raise_for_status()
+client, document = rest_api.start(config, authenticate=True, upload_document=True)
 
 # %%
 # Start and prepare the chat
@@ -173,6 +154,6 @@ def answer(self, prompt, sources):
 
 # %%
 # Before we close the example, let's stop the REST API and have a look at what would
-# have printed in the terminal if we had started it the regular way.
+# have printed in the terminal if we had started it with the `ragna api` command.
 
 rest_api.stop()

docs/examples/gallery_streaming.py

@@ -33,16 +33,21 @@ There are two main ways to generate a configuration file:
 ## Referencing Python objects
 
 Some configuration options reference Python objects, e.g.
-`document = ragna.core.LocalDocument`. You can inject your own objects here and do not
-need to rely on the defaults by Ragna. To do so, make sure that the module the object is
-defined in is on the
-[`PYTHONPATH`](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH). The
-`document` configuration mentioned before internally is roughly treated as
+`document = ragna.core.LocalDocument`. Internally, this is roughly treated as
 `from ragna.core import LocalDocument`.
 
+You can inject your own objects here and do not need to rely on the defaults by Ragna.
+To do so, make sure that the module the object is defined in is on
+[Python's search path](https://docs.python.org/3/library/sys.html#sys.path). There are
+multiple ways to achieve this, e.g.:
+
+- Install your module as part of a package in your current environment.
+- Set the [`PYTHONPATH`](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH)
+  environment variable to include the directory your module is located in.
+
 ## Environment variables
 
-All configuration options can be set or overritten by environment variables by using the
+All configuration options can be set or overridden by environment variables by using the
 `RAGNA_` prefix. For example, `document = ragna.core.LocalDocument` in the configuration
 file is equivalent to setting `RAGNA_DOCUMENT=ragna.core.LocalDocument`.