refactor config docs (#318)

Co-authored-by: Pavithra Eswaramoorthy <[email protected]>

docs/references/config.md

@@ -0,0 +1,116 @@
+# Configuration reference
+
+Ragna uses [TOML](https://toml.io/en/) as language for its configuration file. The
+`ragna` CLI defaults to `ragna.toml` in the current working directory. This behavior can
+be overritten in two ways:
+
+1. The `RAGNA_CONFIG` environment variable.
+2. The `-c` / `--config` option of the `ragna` CLI subcommands.
+
+The CLI option takes precedence over the environment variable.
+
+There are two main ways to generate a configuration file:
+
+1. Running `ragna init` in a terminal starts an interactive wizard that guides you
+   through the generation. The example configuration below is the result of choosing the
+   first option the wizard offers you.
+2. The configuration can also be created programmatically from Python. The example
+   configuration below is the result of the following snippet.
+
+   ```python
+   from ragna.deploy import Config
+
+   config = Config()
+   config.to_file("ragna.toml")
+   ```
+
+## Example
+
+```toml
+{{ config }}
+```
+
+## 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
+`from ragna.core import LocalDocument`.
+
+## Environment variables
+
+All configuration options can be set or overritten 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`.
+
+For configuration options in subsections, the subsection name needs to be appended to
+the prefix, e.g. `RAGNA_COMPONENTS_`. The value needs to be in JSON format. For example
+
+```toml
+[components]
+assistants = [
+    "ragna.assistants.RagnaDemoAssistant",
+]
+```
+
+is equivalent to
+`RAGNA_COMPONENTS_ASSISTANTS='["ragna.assistants.RagnaDemoAssistant"]'`.
+
+## Configuration options
+
+### `local_cache_root`
+
+### `document`
+
+[ragna.core.Document][] class to use to upload and read documents.
+
+### `authentication`
+
+[ragna.deploy.Authentication][] class to use for authenticating users.
+
+### `components`
+
+#### `source_storages`
+
+[ragna.core.SourceStorage][]s to be available for the user to use.
+
+#### `assistants`
+
+[ragna.core.Assistant][]s to be available for the user to use.
+
+### `api`
+
+#### `url`
+
+1. Hostname and port the REST API server will be bound to.
+2. URL of the REST API to be accessed by the web UI.
+
+#### `origins`
+
+[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) origins that are allowed
+to connect to the REST API. The URL of the web UI is required for it to function.
+
+#### `database_url`
+
+URL of a SQL database that will be used to store the Ragna state. See
+[SQLAlchemy documentation](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)
+on how to format the URL.
+
+#### `root_path`
+
+A path prefix handled by a proxy that is not seen by the REST API, but is seen by
+external clients.
+
+### `ui`
+
+#### `url`
+
+Hostname and port the web UI server will be bound to.
+
+#### `origins`
+
+[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) origins that are allowed
+to connect to the web UI.

docs/tutorials/python-api.md

@@ -40,7 +40,7 @@ config = Config()
 config
 ```
 
-Learn more in [Set configuration](../how-tos/set-configuration.md).
+Learn more in [Configuration reference](../references/config.md).
 
 ## Step 2: Upload relevant documents
 

docs/tutorials/rest-api.md

@@ -28,7 +28,7 @@ from ragna import Config
 config = Config.from_file("ragna.toml")
 ```
 
-Learn more in [How to set configuration](../how-tos/set-configuration.md).
+Learn more in [Configuration reference](../references/config.md).
 
 ## Step 2: Start and connect to the API
 

mkdocs.yml

@@ -80,14 +80,13 @@ nav:
       - "tutorials/python-api.md"
       - "tutorials/rest-api.md"
       - "tutorials/web-app.md"
-  - How-to:
-      - "how-tos/set-configuration.md"
   - Community:
       - "community/welcome.md"
       - "community/contribute.md"
   - References:
       - "references/python-api.md"
-      - "references/rest-api.md"
       - "references/cli.md"
+      - "references/config.md"
+      - "references/rest-api.md"
       - "references/faq.md"
       - "references/release-notes.md"

ragna/deploy/_config.py

@@ -110,6 +110,11 @@ def from_file(cls, path: Union[str, Path]) -> Config:
         with open(path) as file:
             return cls.model_validate(tomlkit.load(file).unwrap())
 
+    def __str__(self) -> str:
+        toml = tomlkit.item(self.model_dump(mode="json"))
+        self._set_multiline_array(toml)
+        return toml.as_string()
+
     def _set_multiline_array(self, item: tomlkit.items.Item) -> None:
         if isinstance(item, tomlkit.items.Array):
             item.multiline(True)
@@ -128,8 +133,5 @@ def to_file(self, path: Union[str, Path], *, force: bool = False) -> None:
         if path.exists() and not force:
             raise RagnaException(f"{path} already exist.")
 
-        toml = tomlkit.item(self.model_dump(mode="json"))
-        self._set_multiline_array(toml)
-
         with open(path, "w") as file:
-            file.write(toml.as_string())
+            file.write(str(self))

scripts/docs/gen_files.py

@@ -15,6 +15,7 @@
 def main():
     cli_reference()
     api_reference()
+    config_reference()
 
 
 def cli_reference():
@@ -54,4 +55,12 @@ def api_reference():
         json.dump(openapi_json, file)
 
 
+def config_reference():
+    with mkdocs_gen_files.open("references/config.md", "r+") as file:
+        content = file.read().replace("{{ config }}", str(Config()))
+        file.seek(0)
+        file.write(content)
+        file.truncate()
+
+
 main()