From 77228b8a6f7e9b694d8879fd8512bd4ab5cfdcd0 Mon Sep 17 00:00:00 2001 From: Simon Lloyd Date: Wed, 25 Feb 2026 00:12:00 +0000 Subject: [PATCH] docs: re-arange api reference --- .github/workflows/docs.yml | 2 ++ .gitignore | 1 + .readthedocs.yml | 1 + Makefile | 2 ++ docs/api/{index.md => aimbat.md} | 2 +- docs/api/aimbat/aimbat_types.md | 9 +++++++++ docs/api/aimbat/app.md | 9 +++++++++ docs/api/aimbat/cli.md | 9 +++++++++ docs/api/aimbat/core.md | 9 +++++++++ docs/api/aimbat/db.md | 9 +++++++++ docs/api/aimbat/io.md | 9 +++++++++ docs/api/aimbat/logger.md | 9 +++++++++ docs/api/aimbat/models.md | 9 +++++++++ docs/api/aimbat/utils.md | 9 +++++++++ docs/usage/defaults.md | 14 ++++++++++++++ src/aimbat/__init__.py | 2 ++ src/aimbat/_config.py | 28 +++++++++++++++++++++++++++- src/aimbat/core/_data.py | 6 +++--- zensical.toml | 13 ++++++++++++- 19 files changed, 146 insertions(+), 6 deletions(-) rename docs/api/{index.md => aimbat.md} (84%) create mode 100644 docs/api/aimbat/aimbat_types.md create mode 100644 docs/api/aimbat/app.md create mode 100644 docs/api/aimbat/cli.md create mode 100644 docs/api/aimbat/core.md create mode 100644 docs/api/aimbat/db.md create mode 100644 docs/api/aimbat/io.md create mode 100644 docs/api/aimbat/logger.md create mode 100644 docs/api/aimbat/models.md create mode 100644 docs/api/aimbat/utils.md create mode 100644 docs/usage/defaults.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 64590a2..ac8a00f 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index bbe2a13..36a7cfb 100644 --- a/.gitignore +++ b/.gitignore @@ -32,6 +32,7 @@ junit.xml reset_project.sh .envrc aimbat.log +docs/usage/defaults-table.md .env aimbat_test.log GEMINI.md diff --git a/.readthedocs.yml b/.readthedocs.yml index 9a5cc77..14425f8 100644 --- a/.readthedocs.yml +++ b/.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/ diff --git a/Makefile b/Makefile index 1faafcc..bb9900d 100644 --- a/Makefile +++ b/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 diff --git a/docs/api/index.md b/docs/api/aimbat.md similarity index 84% rename from docs/api/index.md rename to docs/api/aimbat.md index d3a7189..de7b12d 100644 --- a/docs/api/index.md +++ b/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 diff --git a/docs/api/aimbat/aimbat_types.md b/docs/api/aimbat/aimbat_types.md new file mode 100644 index 0000000..04d0c29 --- /dev/null +++ b/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 diff --git a/docs/api/aimbat/app.md b/docs/api/aimbat/app.md new file mode 100644 index 0000000..f7d4753 --- /dev/null +++ b/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 diff --git a/docs/api/aimbat/cli.md b/docs/api/aimbat/cli.md new file mode 100644 index 0000000..d698c24 --- /dev/null +++ b/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 diff --git a/docs/api/aimbat/core.md b/docs/api/aimbat/core.md new file mode 100644 index 0000000..1368219 --- /dev/null +++ b/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 diff --git a/docs/api/aimbat/db.md b/docs/api/aimbat/db.md new file mode 100644 index 0000000..39d59dc --- /dev/null +++ b/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 diff --git a/docs/api/aimbat/io.md b/docs/api/aimbat/io.md new file mode 100644 index 0000000..ee57827 --- /dev/null +++ b/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 diff --git a/docs/api/aimbat/logger.md b/docs/api/aimbat/logger.md new file mode 100644 index 0000000..760dc80 --- /dev/null +++ b/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 diff --git a/docs/api/aimbat/models.md b/docs/api/aimbat/models.md new file mode 100644 index 0000000..ff31af5 --- /dev/null +++ b/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 diff --git a/docs/api/aimbat/utils.md b/docs/api/aimbat/utils.md new file mode 100644 index 0000000..76b404d --- /dev/null +++ b/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 diff --git a/docs/usage/defaults.md b/docs/usage/defaults.md new file mode 100644 index 0000000..dd0a64c --- /dev/null +++ b/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_` (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 `.env`). + +--8<-- "docs/usage/defaults-table.md" + +!!! tip + To view the settings currently in use, run `aimbat utils settings`. diff --git a/src/aimbat/__init__.py b/src/aimbat/__init__.py index f2fb085..25b876f 100644 --- a/src/aimbat/__init__.py +++ b/src/aimbat/__init__.py @@ -16,4 +16,6 @@ from ._config import settings as settings +__all__ = ["settings"] + name = "aimbat" diff --git a/src/aimbat/_config.py b/src/aimbat/_config.py index 12227c7..38e9d74 100644 --- a/src/aimbat/_config.py +++ b/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="") diff --git a/src/aimbat/core/_data.py b/src/aimbat/core/_data.py index 1a3b599..3507859 100644 --- a/src/aimbat/core/_data.py +++ b/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, ): diff --git a/zensical.toml b/zensical.toml index 3e6e732..4cc7b5e 100644 --- a/zensical.toml +++ b/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"},