From 79ad3584d2c5f2e8a6f1687bb8f07b40ecf3727e Mon Sep 17 00:00:00 2001 From: DOKOS-TAYOS Date: Tue, 22 Sep 2026 20:27:50 +0200 Subject: [PATCH 1/7] docs: refresh documentation after 1.0.0 --- CHANGELOG.md | 4 ++ README.md | 7 +--- docs/api/frontend.rst | 12 ++++++ docs/architecture.md | 21 +++++++++- docs/complex-problems.md | 3 +- docs/configuration.md | 11 ++++++ docs/developer-guide.md | 13 ++++-- docs/faq.md | 17 ++++---- docs/getting-started.md | 15 ++++--- docs/index.md | 5 ++- docs/testing.md | 16 +++++--- docs/user-guide.md | 55 +++++++++++++++++++------- src/frontend/ui_dialogs/help_dialog.py | 36 ++++++++++------- 13 files changed, 150 insertions(+), 65 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ff29353..a013e21 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- Synchronized maintained user, developer, API, and in-app reference documentation with the published 1.0.0 implementation. + ## [1.0.0] - 2026-09-22 ### Changed diff --git a/README.md b/README.md index fe6e58f..aa1b06d 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ vector 2D PDEs, function transforms, and specialized scientific simulation workf - Safe expression parsing with AST validation - Unified `f[...]` notation (`f[0]`, `f[1]`, `f[i,k]`) - Interactive result dialogs with derivative/component selection and dynamic redraw -- CSV, JSON, and static figure exports, plus MP4 export for every interactive animation result view +- CSV and JSON data exports, static figure export through the Matplotlib toolbar, and MP4 export from animated views - Environment-backed configuration through `.env` and the in-app `Settings` dialog - Rotating application logs with optional console output @@ -184,10 +184,7 @@ differential-lab To build docs locally: ```bash -pip install -e ".[docs]" -cd docs -make html # Linux/macOS -make.bat html # Windows +python -m sphinx -W --keep-going -b html docs docs/_build/html ``` Output directory: `docs/_build/html/`. diff --git a/docs/api/frontend.rst b/docs/api/frontend.rst index abd6d8c..c96a7d1 100644 --- a/docs/api/frontend.rst +++ b/docs/api/frontend.rst @@ -50,6 +50,18 @@ frontend.ui_dialogs.parameters_dialog .. automodule:: frontend.ui_dialogs.parameters_dialog :members: +frontend.ui_dialogs.solve_session +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: frontend.ui_dialogs.solve_session + :members: + +frontend.ui_dialogs.symbol_palette +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: frontend.ui_dialogs.symbol_palette + :members: + frontend.ui_dialogs.result_dialog ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/architecture.md b/docs/architecture.md index 761a725..a19d43b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -44,13 +44,19 @@ docs/ ```text EquationDialog - -> ParametersDialog + -> SolveSession -> ParametersDialog -> run_solver_pipeline -> validation + parser + solver dispatch -> statistics + metadata -> ResultDialog ``` +`frontend.ui_dialogs.solve_session` owns the UI-only state between Equation and +Configuration. It keeps family-specific browser/custom-editor state and +configuration snapshots, so Equation -> Configuration navigation retains input; +Results -> `Modify setup` returns to the compatible Configuration state rather +than reconstructing it from scratch. + The key design goal is to keep the general solver stack independent from UI-specific behavior. Plot generation is deferred to result dialogs so users can switch views without re-solving. @@ -141,6 +147,11 @@ Core pieces: - `problem_docs.py`: structured help metadata shown in plugin dialogs - `common/`: shared helpers for plugin modules +The shared Advanced Problem infrastructure in `complex_problems/common/` covers +dialog layout, validation, expression handling, documentation panels, background +execution, and result-dialog/animation cleanup. Plugins should reuse it instead +of duplicating UI shells or lifecycle logic. + Plugin contract: - `problem.py` exposes `PROBLEM` with descriptor and `open_dialog(parent)` @@ -186,8 +197,16 @@ If file logging cannot start, the logger falls back to console output. - Solver input is validated before dispatch. - Solver failures are converted into user-facing dialog errors where possible. - Long-running plugin solvers use background helpers and loading dialogs. +- `frontend.performance_guard` estimates dense output, sparse PDE grids, + volumetric histories, and selected Advanced Problem workloads before a GUI run; + it advises or requests confirmation but does not change numerical settings. - Export paths are centralized through `config.paths`. +Standard Results owns CSV/JSON data export actions and delegates static-figure +export to the Matplotlib toolbar. Animated views expose MP4 only where their +plot payload supports it. Advanced-result derived caches (for example 3D slices +and streamlines) remain in result dialogs rather than solver result objects. + ## Quality Tooling - Tests: `pytest` diff --git a/docs/complex-problems.md b/docs/complex-problems.md index 8855e17..3868dd1 100644 --- a/docs/complex-problems.md +++ b/docs/complex-problems.md @@ -129,7 +129,8 @@ instantaneous decomposition. The optional diagnostic residual is - Increase grid resolution only after the model behaves as expected. - Keep time steps conservative for nonlinear or wave-dominated models. - For 2D models, tune both spatial resolution and output sampling cadence. -- Large animations and high-resolution fields can become memory-heavy. +- For Aerodynamics 3D, `nx`, `ny`, `nz`, and the saved-frame cadence multiply retained volumetric history; build its streamline cache only when needed. +- Large animations, MP4 export, and high-resolution fields can become memory-heavy. ## Extending with New Plugins diff --git a/docs/configuration.md b/docs/configuration.md index 3105d72..31269f8 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -14,6 +14,17 @@ DifferentialLab reads configuration from `.env` in the project root. - `int` and `float`: parsed numerically, with range checks where defined - `str`: must be non-empty; some keys enforce a fixed option list +## Settings Dialog + +The in-app `Settings` dialog presents the schema as four operational groups: +`Appearance`, `Plots`, `Solver Defaults`, and `Advanced`. The technical `.env` +key remains available in each control's tooltip. Colour settings have an editable +preview; selecting it opens the system colour chooser. + +`Restore Defaults` repopulates the current form but does not write `.env`. +Choose `Save & Restart` to validate and save the form, then restart the app so +the changed settings are applied. + ## UI Settings | Key | Type | Default | Description | diff --git a/docs/developer-guide.md b/docs/developer-guide.md index a391fa2..672b12a 100644 --- a/docs/developer-guide.md +++ b/docs/developer-guide.md @@ -53,6 +53,8 @@ pip install -e ".[docs]" - Prefer typed dataclasses for solver outputs. - Validate user input before solver invocation. - Reuse helpers in `complex_problems/common` instead of duplicating dialog logic. +- Reuse `frontend.ui_dialogs.solve_session` for retained standard-workflow state + and `frontend.ui_dialogs.symbol_palette` for supported expression insertion. - Keep plugin defaults computationally reasonable for interactive use. - Keep public-facing docs aligned with `pyproject.toml`, `ENV_SCHEMA`, and the plugin registry. @@ -108,21 +110,24 @@ pytest tests/test_nonlinear_waves_solver.py pytest tests/test_schrodinger_td_solver.py pytest tests/test_antenna_radiation_solver.py pytest tests/test_aerodynamics_2d_solver.py +pytest tests/test_aerodynamics_3d.py +pytest tests/test_gravitational_n_body.py +pytest tests/test_fput_experiment.py pytest tests/test_pipe_flow_solver.py +pytest tests/test_advanced_config_dialog_ui.py +pytest tests/test_complex_problem_result_dialog_ui.py ``` ## Documentation Workflow ```bash -pip install -e ".[docs]" -cd docs -make html +python -m sphinx -W --keep-going -b html docs docs/_build/html ``` For Windows: ```bat -make.bat html +python -m sphinx -W --keep-going -b html docs docs/_build/html ``` Documentation should be updated when a change affects: diff --git a/docs/faq.md b/docs/faq.md index e565c83..c590a4b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -55,10 +55,11 @@ logs/run.log ## Complex problem runs too slowly -- Reduce grid size (`nx`, `ny`) and simulation horizon (`t_max`). -- Increase output sampling interval where available. -- Start from defaults and scale up incrementally. -- For animation-heavy results, reduce stored frames before increasing resolution. +- Start from the module defaults or a lower resolution before scaling up. +- For 2D models, reduce `nx` and `ny`; for Aerodynamics 3D, reduce `nx`, `ny`, and `nz`. +- Shorten `t_max` and increase the saved-output interval where available; large volumetric histories consume memory quickly. +- Build the Aerodynamics 3D streamline cache only when needed: it traces every saved frame and remains cached for that Results window. +- Treat animation and MP4 export as additional work, especially for long histories or volumetric views. ## Numerical blow-up or NaNs @@ -84,19 +85,17 @@ logs/run.log ## Sphinx docs build errors - Install docs extras: `pip install -e ".[docs]"`. -- Build from the `docs/` directory. +- Build from the repository root. - Remove stale `docs/_build/` if needed and rebuild. Windows: ```bat -cd docs -make.bat html +python -m sphinx -W --keep-going -b html docs docs/_build/html ``` Linux/macOS: ```bash -cd docs -make html +python -m sphinx -W --keep-going -b html docs docs/_build/html ``` diff --git a/docs/getting-started.md b/docs/getting-started.md index e4e1543..82f86b4 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -125,18 +125,17 @@ differential-lab ## First Run Checklist 1. Open `Solve Equation`. -2. Run a predefined equation to confirm the solver and result dialog work. -3. Open `Settings` and save your preferred UI/plot defaults. -4. Confirm `output/` receives CSV, JSON, plot, or animation exports. -5. Optionally open `Advanced Problems` and run one module with default parameters. +2. Use the searchable predefined-equation browser, select an equation, and choose `Continue`. +3. Review the retained Configuration form, then choose `Solve`. +4. Inspect the Results workspace summary, metrics, diagnostics, and available visualization controls. +5. Use the fixed footer's CSV or JSON action, the Matplotlib toolbar for a static figure, or MP4 only from an animated view. +6. Open `Settings` and save your preferred UI/plot defaults. +7. Optionally open `Advanced Problems` and run one module with default parameters. ## Build Docs Locally ```bash -pip install -e ".[docs]" -cd docs -make html # Linux/macOS -make.bat html # Windows +python -m sphinx -W --keep-going -b html docs docs/_build/html ``` Open `docs/_build/html/index.html`. diff --git a/docs/index.md b/docs/index.md index ac450b3..80e191d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,8 @@ workflows. The current repository includes: - scalar ODE solving - vector ODE systems - difference and recurrence equations -- 2D PDE workflows +- scalar elliptic 2D and 3D PDE workflows +- linear strongly elliptic Vector PDE systems in 2D - function transforms - specialized `complex_problems` plugins - Sphinx-generated API documentation @@ -17,7 +18,7 @@ workflows. The current repository includes: - Python: `>=3.12` - Predefined equation catalog: [`src/config/equations/`](../src/config/equations/) -- Complex problem plugins: 7 registered modules +- Advanced Problems: 10 registered, lazily loaded plugins - Configuration source of truth: `src/config/env.py` - Main entry point: `src/main_program.py` diff --git a/docs/testing.md b/docs/testing.md index 16e52ac..671c33a 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -38,7 +38,12 @@ pytest tests/test_nonlinear_waves_solver.py pytest tests/test_schrodinger_td_solver.py pytest tests/test_antenna_radiation_solver.py pytest tests/test_aerodynamics_2d_solver.py +pytest tests/test_aerodynamics_3d.py +pytest tests/test_gravitational_n_body.py +pytest tests/test_fput_experiment.py pytest tests/test_pipe_flow_solver.py +pytest tests/test_advanced_config_dialog_ui.py +pytest tests/test_complex_problem_result_dialog_ui.py ``` Frontend and utilities: @@ -91,14 +96,15 @@ Run `pyright` when it is installed in your environment. Docs verification: ```bash -pip install -e ".[docs]" -cd docs -make html +python -m sphinx -W --keep-going -b html docs docs/_build/html ``` On Windows, use: ```bat -cd docs -make.bat html +python -m sphinx -W --keep-going -b html docs docs/_build/html ``` + +The GitHub Actions quality workflow checks Ruff linting and formatting, pytest, +and Pyright. Packaging smoke checks and a warnings-as-errors Sphinx build are +appropriate local release/documentation checks when those surfaces change. diff --git a/docs/user-guide.md b/docs/user-guide.md index d39775b..54c011e 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -27,7 +27,10 @@ The standard solver path currently supports: - Vector ODE - Vector PDE -You can use the predefined YAML catalog or write custom expressions. +Use the searchable predefined-equation browser or one of the Custom equation +editors. The browser retains its search, category, and selection while you move +through the standard workflow. Custom editors share a SymbolPalette: choosing a +symbol inserts it literally at the last active supported editor. The current catalog has 125 entries: | Type | Entries | @@ -61,6 +64,10 @@ For custom expressions: Typical safe math functions are available (`sin`, `cos`, `exp`, `log`, `sqrt`, etc.). +Select `Continue` to open Configuration. Going back to Equation retains the +selection and raw editor values; Configuration also retains a compatible form +snapshot for each selected equation. + ### 3. Configure numeric parameters Common settings include: @@ -71,7 +78,9 @@ Common settings include: - statistics to compute - PDE operator and visualization mode -For an initial-value ODE, the optional **IVP Event** panel accepts a safe scalar +Configuration forms adapt to the equation family and window size. Optional +controls use progressive disclosure; for example, expand **IVP Event** only for +an initial-value ODE. That panel accepts a safe scalar expression in `x` and the current state, such as `f[0] - 1`. A zero marks an event. **Stop at event** makes it terminal, while direction `-1`, `0`, or `1` selects decreasing, either, or increasing zero crossings. Events are not applied @@ -322,23 +331,37 @@ positive component count retain component and magnitude views. ### 4. Solve and inspect +Choose `Solve` to run the configured equation. The resizable Results workspace +keeps a factual run summary, computed metrics, detected events where applicable, +and collapsible solver diagnostics separate from its visualization area. Controls +can change the current derivative, component, slice, or display without +re-solving, but available views depend on the result type. + +Choose `Modify setup` to return to the retained Configuration state, adjust it, +and solve again. + Result dialogs include: - metadata and solver quality information - selected statistics - interactive plots/tabs - derivative, component, or axis selection without re-solving -- export options for data and figures +- fixed-footer CSV and JSON data actions +- static figure export through the Matplotlib toolbar +- MP4 export from animated views that provide it ## Function Transform Workflow In `Function Transform`: -1. Provide an `f(x)` expression and domain. -2. Select transform type. -3. Tune transform-specific parameters when shown. -4. Switch between curve view and coefficient view. -5. Export transformed data and plots. +1. Provide an editable `f(x)` expression, optional parameters, and domain; the + SymbolPalette can insert directly into the last active field. +2. Select a transform and tune transform-specific parameters when shown. +3. Choose the curve or coefficient display. +4. Press `Update`. Changes to the function, domain, transform, or display stay + pending until this explicit action recomputes the view. +5. Use `Export CSV...` for the displayed data or the Matplotlib toolbar for a + static figure. Available transform types: @@ -369,7 +392,10 @@ Current modules are: - `schrodinger_td` - `antenna_radiation` - `aerodynamics_2d` +- `aerodynamics_3d` - `pipe_flow` +- `gravitational_n_body` +- `fput_experiment` Most plugin dialogs include a collapsed `How to configure` section with: @@ -395,13 +421,12 @@ Common outputs: Use `Settings` in the main menu to edit environment-backed settings. -Categories include: - -- UI colors, fonts, padding, and tooltips -- plot style, fonts, phase-space markers, contour/surface style, and animation -- solver defaults and tolerances -- logging and update checks +Settings has four user-facing groups: `Appearance`, `Plots`, `Solver Defaults`, +and `Advanced`. Colour fields show an editable preview and open the system colour +chooser. Technical `.env` key names remain available as tooltips. -Saving from the dialog restarts the app so settings apply cleanly. +`Restore Defaults` updates the form only; nothing is written until you choose +`Save & Restart`. `Save & Restart` validates and writes the settings, then +restarts the application so the values take effect cleanly. See [Configuration Reference](configuration.md) for the current key list. diff --git a/src/frontend/ui_dialogs/help_dialog.py b/src/frontend/ui_dialogs/help_dialog.py index d8cf8de..252ac03 100644 --- a/src/frontend/ui_dialogs/help_dialog.py +++ b/src/frontend/ui_dialogs/help_dialog.py @@ -39,8 +39,10 @@ "\u2022 2D PDEs — elliptic equations solved with finite differences " "(Poisson, Laplace, general operator-based)\n" "\u2022 3D PDEs — scalar elliptic equations on rectangular grids with slice views\n" + "\u2022 Vector PDEs — linear strongly elliptic 2D systems with component-aware views\n" "\u2022 Function transforms — Fourier (FFT), Laplace, Taylor series, " - "Hilbert, and Z-transform\n\n" + "Hilbert, and Z-transform\n" + "\u2022 Advanced Problems \u2014 ten specialized scientific simulation workflows\n\n" "Under the hood the application relies on SciPy's solve_ivp integrator " "for ODEs and finite-difference discretisation for PDEs.\n\n" "Tip: hover over a supported control or move keyboard focus to it to see a " @@ -52,22 +54,25 @@ "advanced problems, help, settings, and exit.\n\n" "Solving an equation step by step:\n" "1. Click Solve Equation.\n" - "2. Pick a predefined equation from the list, or switch to the Custom " - "tab and write your own expression.\n" + "2. Search the predefined equation browser, or switch to the Custom " + "tab and write your own expression. The SymbolPalette inserts into the last active " + "editor.\n" "3. Choose the equation type: ODE, Recurrence, Vector ODE, 2D PDE, 3D PDE, or Vector PDE.\n" "4. Click Continue to open the parameters screen.\n" "5. Set the domain, initial/boundary conditions, evaluation points, " "solver method (for ODEs), and statistics to compute.\n" "6. Press Solve to run the computation.\n" - "7. Explore the results: interactive plots (solution curve, phase space, " - "3-D trajectory, animation), computed statistics, and export options " - "(CSV, JSON, PNG, MP4).\n\n" + "7. Explore the Results workspace: factual run summary, computed metrics, events, " + "collapsible diagnostics, and the views supported by that result. Use Modify setup " + "to return to retained Configuration values. CSV and JSON are in the fixed footer; " + "use the Matplotlib toolbar for a static figure and MP4 only from animated views.\n\n" "Function transforms step by step:\n" "1. Click Function Transform.\n" "2. Enter a scalar function f(x) — for example sin(x) or exp(-a*x).\n" "3. (Optional) Define parameters such as a=1.0, omega=2.\n" "4. Select a transform: Fourier, Laplace, Taylor, Hilbert, or Z-transform.\n" - "5. View the result and export the data to CSV or save the plot." + "5. Press Update to calculate: changes stay pending until Update is pressed. " + "Export the displayed data to CSV or save the plot with the Matplotlib toolbar." ) _CUSTOM_EXPRESSIONS = ( @@ -134,8 +139,8 @@ "statistics in a structured format.\n" "\u2022 Matplotlib toolbar \u2014 use the floppy-disk icon below any plot to " "save it.\n" - "\u2022 MP4 animation \u2014 export a video of the time evolution for vector " - "ODE systems (requires ffmpeg in your PATH).\n\n" + "\u2022 MP4 animation \u2014 export a video from an animated result view that " + "offers it (requires ffmpeg in your PATH).\n\n" "The default output directory is output/." ) @@ -152,18 +157,19 @@ "\u2022 Z-transform \u2014 magnitude spectrum on the unit circle.\n\n" "Display mode: switch between Curve (function vs domain) and " "Coefficients (a\u1d62 vs index) to inspect individual terms.\n\n" - "Use Export CSV or the Matplotlib toolbar to save results." + "Use the SymbolPalette or type directly into the active field. Press Update after " + "changing inputs, transform, or display; then use Export CSV or the Matplotlib " + "toolbar to save results." ) _CONFIGURATION = ( f"Almost every visual and numerical aspect of {APP_NAME} can be customized: " - "UI colours and fonts, plot styling (colours, line width, markers, DPI), " - "solver defaults (method, tolerances, step size), output paths, and " - "logging verbosity.\n\n" + "Appearance, Plots, Solver Defaults, and Advanced settings. Colour previews " + "open the system chooser, while technical .env keys remain available in tooltips.\n\n" "Open Settings from the main menu to edit values in a graphical " "form, or edit the .env file directly with any text editor.\n\n" - "After saving, the application restarts automatically so changes take " - "effect immediately." + "Restore Defaults updates only the form. Choose Save & Restart to save values " + "and restart the application so changes take effect." ) _EVENT_DETECTION = ( From fc50a7789f76c1b0dc5b858371a1458e3799977e Mon Sep 17 00:00:00 2001 From: Alejandro Mata Ali <78550667+DOKOS-TAYOS@users.noreply.github.com> Date: Tue, 22 Sep 2026 20:32:39 +0200 Subject: [PATCH 2/7] Make documentation build command self-contained --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index aa1b06d..20d7817 100644 --- a/README.md +++ b/README.md @@ -184,6 +184,7 @@ differential-lab To build docs locally: ```bash +pip install -e ".[docs]" python -m sphinx -W --keep-going -b html docs docs/_build/html ``` From d802e5a152d60d3a84058210319d1c7a763c649f Mon Sep 17 00:00:00 2001 From: Alejandro Mata Ali <78550667+DOKOS-TAYOS@users.noreply.github.com> Date: Tue, 22 Sep 2026 20:32:42 +0200 Subject: [PATCH 3/7] Clarify documented ODE solver backends --- src/frontend/ui_dialogs/help_dialog.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/frontend/ui_dialogs/help_dialog.py b/src/frontend/ui_dialogs/help_dialog.py index 252ac03..d27c55f 100644 --- a/src/frontend/ui_dialogs/help_dialog.py +++ b/src/frontend/ui_dialogs/help_dialog.py @@ -43,8 +43,8 @@ "\u2022 Function transforms — Fourier (FFT), Laplace, Taylor series, " "Hilbert, and Z-transform\n" "\u2022 Advanced Problems \u2014 ten specialized scientific simulation workflows\n\n" - "Under the hood the application relies on SciPy's solve_ivp integrator " - "for ODEs and finite-difference discretisation for PDEs.\n\n" + "Under the hood the application uses SciPy IVP/BVP integrators for ODE workflows " + "and finite-difference discretisation for PDEs.\n\n" "Tip: hover over a supported control or move keyboard focus to it to see a " "short contextual tooltip." ) From b4326580b98f4dde617668301085798ebbd75baa Mon Sep 17 00:00:00 2001 From: Alejandro Mata Ali <78550667+DOKOS-TAYOS@users.noreply.github.com> Date: Tue, 22 Sep 2026 20:33:04 +0200 Subject: [PATCH 4/7] Keep getting-started docs build copyable --- docs/getting-started.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index 82f86b4..9810af0 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -135,6 +135,7 @@ differential-lab ## Build Docs Locally ```bash +pip install -e ".[docs]" python -m sphinx -W --keep-going -b html docs docs/_build/html ``` From 626f9e1682adca38ad02c9fda1c10340ef097b7f Mon Sep 17 00:00:00 2001 From: Alejandro Mata Ali <78550667+DOKOS-TAYOS@users.noreply.github.com> Date: Tue, 22 Sep 2026 20:33:09 +0200 Subject: [PATCH 5/7] Document docs extras before Sphinx verification --- docs/testing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/testing.md b/docs/testing.md index 671c33a..3375482 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -96,6 +96,7 @@ Run `pyright` when it is installed in your environment. Docs verification: ```bash +pip install -e ".[docs]" python -m sphinx -W --keep-going -b html docs docs/_build/html ``` From 8f245c86f602618194af5cbef0599e7bbebf6d26 Mon Sep 17 00:00:00 2001 From: Alejandro Mata Ali <78550667+DOKOS-TAYOS@users.noreply.github.com> Date: Tue, 22 Sep 2026 20:34:08 +0200 Subject: [PATCH 6/7] Document Settings validation at startup --- docs/configuration.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 31269f8..e938b89 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -22,8 +22,9 @@ key remains available in each control's tooltip. Colour settings have an editabl preview; selecting it opens the system colour chooser. `Restore Defaults` repopulates the current form but does not write `.env`. -Choose `Save & Restart` to validate and save the form, then restart the app so -the changed settings are applied. +Choose `Save & Restart` to write the form values and restart the app. On startup, +values are validated against `ENV_SCHEMA`; invalid values fall back to schema defaults +and are logged. ## UI Settings From b6ee00591f11923d060586f72baaf38723bc93ab Mon Sep 17 00:00:00 2001 From: Alejandro Mata Ali <78550667+DOKOS-TAYOS@users.noreply.github.com> Date: Tue, 22 Sep 2026 20:34:13 +0200 Subject: [PATCH 7/7] Clarify Settings save and startup validation --- docs/user-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide.md b/docs/user-guide.md index 54c011e..d725ecf 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -426,7 +426,7 @@ and `Advanced`. Colour fields show an editable preview and open the system colou chooser. Technical `.env` key names remain available as tooltips. `Restore Defaults` updates the form only; nothing is written until you choose -`Save & Restart`. `Save & Restart` validates and writes the settings, then -restarts the application so the values take effect cleanly. +`Save & Restart`. `Save & Restart` writes the settings and restarts the application; +startup validation then applies the schema rules and falls back to defaults for invalid values. See [Configuration Reference](configuration.md) for the current key list.