From b8878d693009e322ab0315877265cfaf943ca266 Mon Sep 17 00:00:00 2001 From: Julian Stirling Date: Wed, 11 Mar 2026 12:58:35 +0000 Subject: [PATCH] Removing out of date developer doc information and improving linking --- apidocs/dev/config-file.md | 16 ++++++++-------- apidocs/dev/python.md | 12 +++++++----- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/apidocs/dev/config-file.md b/apidocs/dev/config-file.md index 906aea83..5c1e160a 100644 --- a/apidocs/dev/config-file.md +++ b/apidocs/dev/config-file.md @@ -4,7 +4,7 @@ By default, this configuration file is read from `/var/openflexure/settings/ofm_ The default configuration file links to the configuration file in the repository: -``` +```json { "base_config_file": "/var/openflexure/application/openflexure-microscope-server/ofm_config_full.json" } @@ -12,7 +12,7 @@ The default configuration file links to the configuration file in the repository ## Understanding and modifying the base configuration file -This section describes how to change the microscope configuration for development. For example, when making a Merge Request to add a new Thing to the standard microscope configuration. **Do not do this for customising a single microscope.** For customising the configuration of a single microscope see the next section. +This section describes how to change the microscope configuration for development. For example, when making a Merge Request to add a new Thing to the standard microscope configuration. **Do not do this for customising a single microscope.** For customiston please refeer to the section on [customising the configuration](#section-customise-config). The specification for the configuration file is set by [LabThings FastAPI](https://labthings-fastapi.readthedocs.io/). The file is a JSON file. As such, it cannot contain comments. @@ -31,7 +31,7 @@ The `things` dictionary can specify a `Thing` to be loaded into the server in tw For example: -``` +```json "autofocus": "openflexure_microscope_server.things.autofocus:AutofocusThing", ``` @@ -46,7 +46,7 @@ If further information needs to be supplied then the value should be a dictionar For example: -``` +```json "camera": { "class": "openflexure_microscope_server.things.camera.picamera:StreamingPiCamera2", "kwargs": { @@ -55,7 +55,8 @@ For example: } ``` -## Customising the configuration +## Customising the configuration :id=section-customise-config + To have a custom configuration for a specific microscope, we recommend editing `ofm_config.json` in the settings folder. **Avoid editing the base configuration in the repository.** This will keep your customisations that should not be pushed separate from changes to the base file. @@ -90,14 +91,13 @@ As the only key that needs changing is `things.camera.kwargs.camera_board` the p } ``` -Note that even though the `camera` patch is specified as: +This will change the camera section to: ```json "camera": { + "class": "openflexure_microscope_server.things.camera.picamera:StreamingPiCamera2", "kwargs": { "camera_board": "picamera_hq" } } ``` - -This only affects the specified keys. So the camera class is unaffected. diff --git a/apidocs/dev/python.md b/apidocs/dev/python.md index 04caaab9..7b2af3eb 100644 --- a/apidocs/dev/python.md +++ b/apidocs/dev/python.md @@ -3,14 +3,13 @@ ## Overview -Ideally, Python code should be: +Python code should be: * Broken up into small, clear, testable functions. * Documented with docstrings (For conventions see below). * Type hinted * Covered by unit tests (using [pytest](https://docs.pytest.org)) -The server code is going through significant flux during the transition from v2 to v3, so currently our test coverage is being rebuilt and type checking does not yet pass. ## Python environment, build, and dependencies @@ -28,17 +27,19 @@ As of `v3` we specify dependencies in `pyproject.toml`. These are not currently * To lint, run `ruff check` and manually fix any flagged issues * To auto-format the Python code run `ruff format` +* To check for spelling errors `codespell .` **Before pushing** please auto-format your code and also run the quality checks (linting, static analysis, and unit tests) * All commands above * `pytest` +* `mypy src` -We use several code analysis and formatting libraries in this project. Our CI will check each of these automatically, so ensuring they pass locally will save you time. Currently `ruff` is used for linting/formatting and `pytest` for unit tests. `mypy` will be enabled once the codebase is ready. +We use several code analysis and formatting libraries in this project. Our CI will check each of these automatically, so ensuring they pass locally will save you time. Currently `ruff` is used for linting/formatting and `pytest` for unit tests. -To check your code before each commit we recommend putting the following script in tour `.git/hooks` directory with the filename `pre-commit`. +To check your code before each commit we recommend putting the following script in your `.git/hooks` directory with the filename `pre-commit`. ```python @@ -50,13 +51,14 @@ function angrymessage() { RED='\033[1;31m' NC='\033[0m' # No Color - printf "\n${RED}Not committing as ruff failed${NC}\n\n" + printf "\n${RED}Not committing as ruff or spellcheck failed${NC}\n\n" } trap angrymessage ERR ruff format --check ruff check +codespell . ```