refactor config docs

docs/references/config.md

@@ -0,0 +1,117 @@
+# 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 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"]'`.
+
+## Reference
+
+### `local_cache_root`
+
+### `document`
+
+[ragna.core.Document][] class to use to upload and read documents.
+
+### `authentication`
+
+[ragna.deploy.Authentication][] class to use.
+
+### `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 function.
+
+#### `database_url`
+
+URL of a SQL database that will be used to store the Ragna state. See
+[this reference](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls) on
+how to format the URL. `"memory"` is a special case, which will use a non-persistent,
+in-memory [SQLite](https://www.sqlite.org/index.html) database.
+
+#### `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 [Set configuration](../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 [How to set configuration](../references/config.md).
 
 ## Step 2: Start and connect to the API
 

mkdocs.yml

@@ -79,14 +79,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"

scripts/docs/gen_files.py

@@ -1,7 +1,10 @@
 import contextlib
 import io
 import json
+import shutil
+import tempfile
 import unittest.mock
+from pathlib import Path
 
 import fastapi.openapi.utils
 import mkdocs_gen_files
@@ -15,6 +18,7 @@
 def main():
     cli_reference()
     api_reference()
+    config_reference()
 
 
 def cli_reference():
@@ -54,4 +58,19 @@ def api_reference():
         json.dump(openapi_json, file)
 
 
+def config_reference():
+    directory = Path(tempfile.mkdtemp())
+    config_path = directory / "ragna.toml"
+    Config().to_file(config_path)
+    with open(config_path) as file:
+        config_content = file.read()
+    shutil.rmtree(str(directory))
+
+    with mkdocs_gen_files.open("references/config.md", "r") as file:
+        content = file.read().replace("{{ config }}", config_content)
+
+    with mkdocs_gen_files.open("references/config.md", "w") as file:
+        file.write(content)
+
+
 main()