docs: re-arange api reference

.github/workflows/docs.yml

@@ -27,6 +27,8 @@ jobs:
       - name: Install docs dependencies
         run: |
           uv sync --locked --no-dev --group docs
+      - name: Generate defaults table
+        run: uv run python -m aimbat._config > docs/usage/defaults-table.md
       - name: Build site
         run: uv run zensical build --clean
       - name: Upload artifact

.gitignore

@@ -32,6 +32,7 @@ junit.xml
 reset_project.sh
 .envrc
 aimbat.log
+docs/usage/defaults-table.md
 .env
 aimbat_test.log
 GEMINI.md

.readthedocs.yml

@@ -16,6 +16,7 @@ build:
       - asdf global uv latest
       - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --locked --no-dev --group docs
     post_build:
+      - uv run python -m aimbat._config > docs/usage/defaults-table.md
       - uv run zensical build --clean
       - mkdir -p $READTHEDOCS_OUTPUT/html/
       - cp -r site/* $READTHEDOCS_OUTPUT/html/

Makefile

@@ -46,9 +46,11 @@ mypy: check-uv ## Run typing tests with pytest.
 	uv run pytest --mypy -m mypy src tests
 
 docs: check-uv sync ## Build html docs.
+	uv run python -m aimbat._config > docs/usage/defaults-table.md
 	uv run zensical build --clean
 
 live-docs: check-uv sync ## Live build html docs. They are served on http://localhost:8000
+	uv run python -m aimbat._config > docs/usage/defaults-table.md
 	uv run zensical serve
 
 changelog: check-uv sync ## Generate CHANGELOG.md

docs/api/index.md → docs/api/aimbat.md

@@ -4,5 +4,5 @@
       show_root_heading: true
       show_root_toc_entry: true
       inherited_members: true
-      show_submodules: true
+      show_submodules: false
       summary: true

docs/api/aimbat/aimbat_types.md

@@ -0,0 +1,9 @@
+::: aimbat.aimbat_types
+    options:
+      heading_level: 1
+      toc_label: aimbat.aimbat_types
+      show_root_heading: true
+      show_root_toc_entry: true
+      inherited_members: true
+      show_submodules: true
+      summary: true

docs/api/aimbat/app.md

@@ -0,0 +1,9 @@
+::: aimbat.app
+    options:
+      heading_level: 1
+      toc_label: aimbat.app
+      show_root_heading: true
+      show_root_toc_entry: true
+      inherited_members: true
+      show_submodules: true
+      summary: true

docs/api/aimbat/cli.md

@@ -0,0 +1,9 @@
+::: aimbat.cli
+    options:
+      heading_level: 1
+      toc_label: aimbat.cli
+      show_root_heading: true
+      show_root_toc_entry: true
+      inherited_members: true
+      show_submodules: true
+      summary: true

docs/api/aimbat/core.md

@@ -0,0 +1,9 @@
+::: aimbat.core
+    options:
+      heading_level: 1
+      toc_label: aimbat.core
+      show_root_heading: true
+      show_root_toc_entry: true
+      inherited_members: true
+      show_submodules: true
+      summary: true

docs/api/aimbat/db.md

@@ -0,0 +1,9 @@
+::: aimbat.db
+    options:
+      heading_level: 1
+      toc_label: aimbat.db
+      show_root_heading: true
+      show_root_toc_entry: true
+      inherited_members: true
+      show_submodules: true
+      summary: true

docs/api/aimbat/io.md

@@ -0,0 +1,9 @@
+::: aimbat.io
+    options:
+      heading_level: 1
+      toc_label: aimbat.io
+      show_root_heading: true
+      show_root_toc_entry: true
+      inherited_members: true
+      show_submodules: true
+      summary: true

docs/api/aimbat/logger.md

@@ -0,0 +1,9 @@
+::: aimbat.logger
+    options:
+      heading_level: 1
+      toc_label: aimbat.logger
+      show_root_heading: true
+      show_root_toc_entry: true
+      inherited_members: true
+      show_submodules: true
+      summary: true

docs/api/aimbat/models.md

@@ -0,0 +1,9 @@
+::: aimbat.models
+    options:
+      heading_level: 1
+      toc_label: aimbat.models
+      show_root_heading: true
+      show_root_toc_entry: true
+      inherited_members: true
+      show_submodules: true
+      summary: true

docs/api/aimbat/utils.md

@@ -0,0 +1,9 @@
+::: aimbat.utils
+    options:
+      heading_level: 1
+      toc_label: aimbat.utils
+      show_root_heading: true
+      show_root_toc_entry: true
+      inherited_members: true
+      show_submodules: true
+      summary: true

docs/usage/defaults.md

@@ -0,0 +1,14 @@
+# Defaults
+
+AIMBAT behaviour can be customised via the following settings.
+Each setting can be overridden on a per-project basis (in order of precedence):
+
+- Environment variables of the form `AIMBAT_<SETTING_NAME>` (e.g. `AIMBAT_LOG_LEVEL=DEBUG`).
+- A `.env`[^1] file in the current working directory (e.g. `AIMBAT_LOG_LEVEL=DEBUG`).
+
+[^1]: Literally a file called `.env` (not `<SOMETHING>.env`).
+
+--8<-- "docs/usage/defaults-table.md"
+
+!!! tip
+    To view the settings currently in use, run `aimbat utils settings`.

src/aimbat/__init__.py

@@ -16,4 +16,6 @@
 
 from ._config import settings as settings
 
+__all__ = ["settings"]
+
 name = "aimbat"

src/aimbat/_config.py

@@ -11,6 +11,8 @@
 
 
 class Settings(EventParametersValidatorMixin, BaseSettings):
+    """Global configuration options for the AIMBAT application."""
+
     model_config = SettingsConfigDict(env_prefix="aimbat_", env_file=".env")
 
     project: Path = Field(
@@ -205,5 +207,29 @@ def cli_settings_list(
     print_settings_table(pretty)
 
 
+def generate_settings_table_markdown() -> str:
+    """Generate a markdown table of all AIMBAT default settings."""
+    import json
+
+    env_prefix = Settings.model_config.get("env_prefix", "").upper()
+    values: dict[str, str] = json.loads(settings.model_dump_json())
+
+    lines = [
+        "| Environment Variable | Default | Description |",
+        "|---------------------|---------|-------------|",
+    ]
+
+    for name, value in values.items():
+        field_info = Settings.model_fields.get(name)
+        description = (field_info.description or "" if field_info else "").replace(
+            "|", "\\|"
+        )
+        env_var = f"`{env_prefix}{name.upper()}`"
+        formatted = f"`{value}`" if value != "" else '`""`'
+        lines.append(f"| {env_var} | {formatted} | {description} |")
+
+    return "\n".join(lines) + "\n"
+
+
 if __name__ == "__main__":
-    print(Settings().model_dump())
+    print(generate_settings_table_markdown(), end="")

src/aimbat/core/_data.py

@@ -190,7 +190,7 @@ def _print_dry_run_results(
 
 def add_data_to_project(
     session: Session,
-    datas_sources: Sequence[str | os.PathLike],
+    data_sources: Sequence[str | os.PathLike],
     data_type: DataType,
     dry_run: bool = False,
     disable_progress_bar: bool = True,
@@ -205,7 +205,7 @@ def add_data_to_project(
         disable_progress_bar: Do not display progress bar.
     """
 
-    logger.info(f"Adding {len(datas_sources)} {data_type} files to project.")
+    logger.info(f"Adding {len(data_sources)} {data_type} files to project.")
 
     # Snapshot existing IDs before entering the savepoint so we can identify
     # what would be new vs reused when running a dry run.
@@ -218,7 +218,7 @@ def add_data_to_project(
         added_datasources: list[AimbatDataSource] = []
         with session.begin_nested() as nested:
             for datasource in track(
-                sequence=datas_sources,
+                sequence=data_sources,
                 description="Adding data ...",
                 disable=disable_progress_bar,
             ):

zensical.toml

@@ -19,9 +19,20 @@ nav = [
     {"Using AIMBAT" = "usage/index.md"},
     "usage/cli.md",
     "usage/gui.md",
+    "usage/defaults.md",
   ] },
   { "API reference" = [
-    "api/index.md",
+    "api/aimbat.md",
+    "api/aimbat/app.md",
+    "api/aimbat/aimbat_types.md",
+    "api/aimbat/cli.md",
+    "api/aimbat/core.md",
+    "api/aimbat/db.md",
+    "api/aimbat/io.md",
+    "api/aimbat/logger.md",
+    "api/aimbat/models.md",
+    # "api/aimbat/ui.md",
+    "api/aimbat/utils.md",
   ] },
  { "Getting Help" = "help.md"},
  {"Contributors" = "contributors.md"},