docs: documentation for settings

.gitignore

@@ -4,6 +4,7 @@ data/**/*.jsonl
 products*.jsonl.gz
 data/searchalicious-openapi.yml
 data/searchalicious-config-schema.yml
+data/searchalicious-settings-schema.yml
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

Makefile

@@ -165,9 +165,13 @@ generate-custom-elements: _ensure_network
 	${DOCKER_COMPOSE} run --rm search_nodejs npm run analyze
 
 generate-config-schema: _ensure_network
-	@echo "🔎 Generating config-schema.json …"
+	@echo "🔎 Generating config-schema.yml …"
 	${DOCKER_COMPOSE} run --rm api python3 -m app export-config-schema /opt/search/data/searchalicious-config-schema.yml
 
+generate-settings-schema: _ensure_network
+	@echo "🔎 Generating settings-schema.yml …"
+	${DOCKER_COMPOSE} run --rm api python3 -m app export-settings-schema /opt/search/data/searchalicious-settings-schema.yml
+
 #-------#
 # Tests #
 #-------#

app/cli/main.py

@@ -230,23 +230,17 @@ def export_openapi(
     print(f"spec written to {target_path}")
 
 
-@cli.command()
-def export_config_schema(
-    target_path: Path = typer.Argument(
-        exists=None,
-        file_okay=True,
-        dir_okay=False,
-        help="Path of the YAML or JSON data file",
-    )
+def export_schema(
+    class_: type["app.config.Config"] | type["app.config.Settings"], target_path: Path
 ):
-    """Export Configuration json schema to a file."""
+    """Export schema to a file."""
     import json
 
     import yaml
 
-    from app.config import Config, ConfigGenerateJsonSchema
+    from app.config import ConfigGenerateJsonSchema
 
-    schema = Config.model_json_schema(schema_generator=ConfigGenerateJsonSchema)
+    schema = class_.model_json_schema(schema_generator=ConfigGenerateJsonSchema)
 
     print("writing json schema")
     with open(target_path, "w") as f:
@@ -258,5 +252,29 @@ def export_config_schema(
     print(f"schema written to {target_path}")
 
 
+schema_target_path = typer.Argument(
+    exists=None,
+    file_okay=True,
+    dir_okay=False,
+    help="Path of the YAML or JSON data file",
+)
+
+
+@cli.command()
+def export_config_schema(target_path: Path = schema_target_path):
+    """Export Configuration json schema to a file."""
+    from app.config import Config
+
+    export_schema(Config, target_path)
+
+
+@cli.command()
+def export_settings_schema(target_path: Path = schema_target_path):
+    """Export Configuration json schema to a file."""
+    from app.config import Settings
+
+    export_schema(Settings, target_path)
+
+
 def main() -> None:
     cli()

app/config.py

@@ -15,6 +15,13 @@
 
 
 class LoggingLevel(StrEnum):
+    """Accepted logging levels
+
+    * NOTSET - means no los
+    * DEBUG / INFO / WARNING / ERROR / CRITICAL
+      - match standard Python logging levels
+    """
+
     NOTSET = "NOTSET"
     DEBUG = "DEBUG"
     INFO = "INFO"
@@ -45,27 +52,75 @@ class ScriptType(StrEnum):
 class Settings(BaseSettings):
     """Settings for Search-a-licious
 
-    Those settings can be overriden through environment
+    The most important settings is `config_path`.
+
+    Those settings can be overridden through environment
+    by using the name in capital letters.
+    If you use docker compose, a good way to do that
+    is to modify those values in your .env file.
     """
 
-    #: Path of the search-a-licious yaml configuration file
-    config_path: Path | None = None
-    #: URL to the ElasticSearch instance
-    elasticsearch_url: str = "http://localhost:9200"
-    #: Host for the Redis instance containing event stream
-    redis_host: str = "localhost"
-    #: Port for the redis host instance containing event stream
-    redis_port: int = 6379
-    #: timeout in seconds to read redis event stream
-    redis_reader_timeout: int = 5
-    #: Sentry DNS to report incident, if None no incident is reported
-    sentry_dns: str | None = None
-    #: Log level
-    log_level: LoggingLevel = LoggingLevel.INFO
-    #: Directory where to store taxonomies before ingestion to ElasticSearch
-    taxonomy_cache_dir: Path = Path("data/taxonomies")
-    #: User-Agent used when fetching resources (taxonomies) or documents
-    user_agent: str = "search-a-licious"
+    config_path: Annotated[
+        Path | None,
+        Field(
+            description=cd_(
+                """Path to the search-a-licious yaml configuration file.
+
+                See [Explain configuration file](../explain-configuration/) for more information
+                """
+            )
+        ),
+    ] = None
+    elasticsearch_url: Annotated[
+        str,
+        Field(
+            description=cd_(
+                """URL to the ElasticSearch instance
+
+                Bare in mind this is from inside the container.
+                """
+            )
+        ),
+    ] = "http://localhost:9200"
+    redis_host: Annotated[
+        str,
+        Field(
+            description=cd_(
+                """Host for the Redis instance containing event stream
+
+                Bare in mind this is from inside the container.
+                """
+            )
+        ),
+    ] = "localhost"
+    redis_port: Annotated[
+        int,
+        Field(description="Port for the redis host instance containing event stream"),
+    ] = 6379
+    redis_reader_timeout: Annotated[
+        int, Field(description="timeout in seconds to read redis event stream")
+    ] = 5
+    sentry_dns: Annotated[
+        str | None,
+        Field(
+            description="Sentry DNS to report incident, if None no incident is reported"
+        ),
+    ] = None
+    log_level: Annotated[
+        LoggingLevel, Field(description=f"Log level. {LoggingLevel.__doc__}")
+    ] = LoggingLevel.INFO
+    taxonomy_cache_dir: Annotated[
+        Path,
+        Field(
+            description="Directory where to store taxonomies before ingestion to ElasticSearch"
+        ),
+    ] = Path("data/taxonomies")
+    user_agent: Annotated[
+        str,
+        Field(
+            description="User-Agent used when fetching resources (taxonomies) or documents"
+        ),
+    ] = "search-a-licious"
 
 
 settings = Settings()

docker-compose.yml

@@ -35,7 +35,7 @@ x-api-common: &api-common
   image: ghcr.io/openfoodfacts/search-a-licious/search_service_image:${TAG:-dev}
   restart: ${RESTART_POLICY:-always}
   environment:
-    - ELASTICSEARCH_URL=http://es01:9200
+    - ELASTICSEARCH_URL=${ELASTICSEARCH_URL:-http://es01:9200}
     - SENTRY_DNS
     - LOG_LEVEL
     - REDIS_HOST

docs/users/how-to-install.md

@@ -8,5 +8,4 @@ All configuration are passed through environment variables to services through t
 
 The only required change is to set the `CONFIG_PATH` variable to the path of your YAML configuration file. This file is used to configure the search-a-licious indexer and search services.
 
-
-
+If you want to see more about settings, see the [Reference for Settings](./ref-settings.md)

docs/users/ref-settings.md

@@ -0,0 +1,8 @@
+# Reference for Settings
+
+You can find the [raw json schema here](./searchalicious-settings-schema.yml)
+
+[See Settings documentation on it's own page](./searchalicious-settings-schema.html)
+<iframe src="./searchalicious-settings-schema.html" width="900vw" height="1000vh" style="max-width: 900px; max-height: 1000px;">
+  <!-- This iframe contains documentation generated by scripts/build_schema.sh -->
+</iframe>

scripts/build_schema.sh

@@ -2,28 +2,33 @@
 # Build config documentation in markdown
 # Use it before using mkdocs
 
+# Parameter is the schema type: config / settings
+SCHEMA=$1
+
+[[ -z $SCHEMA ]] && echo "You must provide a schema type: config / settings" && exit 1
+
 set -e
 
 # get group id to use it in the docker
 GID=$(id -g)
 
 # ensure dest dir
-mkdir -p build/ref-config
+mkdir -p build/ref-$SCHEMA
 
 # create yaml
-make generate-config-schema
+make generate-$SCHEMA-schema
 # create image
 docker build --build-arg "USER_UID=$UID" --build-arg "USER_GID=$GID" --tag 'json-schema-for-humans' -f scripts/Dockerfile.schema .
 
 # use image to generate documentation
 docker run --rm --user user \
   -v $(pwd)/scripts/schema-config.json:/docs/schema-config.json \
-  -v $(pwd)/data/searchalicious-config-schema.yml:/docs/in/searchalicious-config-schema.yml \
-  -v $(pwd)/build/ref-config:/docs/out \
+  -v $(pwd)/data/searchalicious-$SCHEMA-schema.yml:/docs/in/searchalicious-$SCHEMA-schema.yml \
+  -v $(pwd)/build/ref-$SCHEMA:/docs/out \
   json-schema-for-humans \
   generate-schema-doc --config-file /docs/schema-config.json /docs/in/ /docs/out/
 
-# copy to ref-config folder
-mv build/ref-config/* gh_pages/users/ref-config/
+# copy to ref-$SCHEMA folder
+mv build/ref-$SCHEMA/* gh_pages/users/ref-$SCHEMA/
 # also source
-cp data/searchalicious-config-schema.yml gh_pages/users/ref-config/
+cp data/searchalicious-$SCHEMA-schema.yml gh_pages/users/ref-$SCHEMA/

scripts/generate_doc.sh

@@ -11,8 +11,9 @@ mkdir -p gh_pages
 echo "Build documentation with MkDocs"
 scripts/build_mkdocs.sh
 
-echo "Generate documentation for configuration file"
-scripts/build_schema.sh
+echo "Generate documentation for configuration file and settings"
+scripts/build_schema.sh config
+scripts/build_schema.sh settings
 
 echo "Generate OpenAPI documentation"
 make generate-openapi