From 59eafa7802f4eda04061378178a979157f5a2e7a Mon Sep 17 00:00:00 2001 From: Julian Stirling Date: Wed, 11 Mar 2026 12:38:18 +0000 Subject: [PATCH] Apply suggestions from code review of branch move-to-dev-docs Co-authored-by: Joe Knapper --- README.md | 2 +- apidocs/dev/README.md | 6 +++--- apidocs/dev/config-file.md | 6 ++++-- apidocs/dev/ofm.css | 2 +- apidocs/dev/python.md | 6 +++--- apidocs/dev/webapp.md | 2 +- 6 files changed, 13 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 00c3262d..4af9d1bf 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ The microscope is initially configured by a LabThings config file. This specifie By default, this configuration file should be read from `/var/openflexure/settings/ofm_config.json` when the microscope is run as a service. If it is run at the command line you should specify the configuration using the `-c` command line flag. This configuration file does not change often, and usually only needs to be updated when you change the physical hardware. It may be that this file should be made read-only, particularly in microscopes deployed for e.g. medical applications. -In the future tool will be created for crating custom microscope configurations. Currently no custom configurations are recommended, except for development. More [information on the configuration file](https://openflexure.gitlab.io/openflexure-microscope-server/dev/index.html#config-file) can be found in the developer documentation. +In the future, a tool will be created for crating custom microscope configurations. Currently no custom configurations are recommended, except for development. More [information on the configuration file](https://openflexure.gitlab.io/openflexure-microscope-server/dev/index.html#config-file) can be found in the developer documentation. The settings folder holds the state of your microscope, including the calibrations. The settings folder is, by default, `/var/openflexure/settings/` if running on a Raspberry Pi, or `./settings/` if run elsewhere. It can be changed in the configuration file. This holds every other persistent setting. Camera settings, calibration data, default capture settings, stream resolution and so on. There is one folder per `Thing`, each with their own file. The settings files can change very regularly, and if you need to reset your settings, it's usually these files that you should remove or reset. If you delete one settings file this should reset the corresponding `Thing`, you don't have to delete the whole folder. diff --git a/apidocs/dev/README.md b/apidocs/dev/README.md index 7788c072..6ae64813 100644 --- a/apidocs/dev/README.md +++ b/apidocs/dev/README.md @@ -84,7 +84,7 @@ To start the simulation server: * Open the address displayed in the terminal in any browser. * To close the simulation server, return to the terminal and press `ctrl + c`. -> Note: If you are using Windows, we advise running this command in PowerShell. If it doesn't work this, might be a permission issue on managed machines, in which case try executing the command in a CMD terminal. +> Note: If you are using Windows, we advise running this command in PowerShell. If it doesn't work, this might be a permission issue on managed machines, in which case try executing the command in a CMD terminal. > Note: If you receive an error saying that port 5000 is already in use, you can specify a different port to run the simulation on using `--port`: > @@ -101,7 +101,7 @@ Please first read our **[project contributions guide](contributing)** * We recommend all development is done on a branch. * If you are editing the web app, please see our see the README in the [webapp](webapp) directory. -* If you want to try a branch with webapp changes (that are already pushed to GitLab), but don't want to compile the javascript, then run `python pull_webapp.py -b ` to get the artifacts from the GitLab CI. +* If you want to try a branch with webapp changes (that are already pushed to GitLab with a passing pipeline), but don't want to compile the javascript, then run `python pull_webapp.py -b ` to get the artifacts from the GitLab CI. **For development on a Raspberry Pi** we recommend VSCode Remote session from another computer. This allows you to use your usual developer environment to write code, but everything runs on the Raspberry Pi with real hardware. Note that the repository is cloned by default over `https`, so you will probably need to change the "remote" URL to your fork of the repository, or to SSH, before you're able to push changes. @@ -109,5 +109,5 @@ Please first read our **[project contributions guide](contributing)** The microscope comprises a number of `Thing` instances, which provide actions and properties to implement hardware control and software features. These may be imported from any Python module, using `ofm_config.json`. See the LabThings-FastAPI documentation for how to create a `Thing`. -Currently, the camera and stage classes are provided by external libraries, `labthings-picamera2` and `labthings-sangaboard`. Replacing these is the easiest way to use alternative hardware: interfaces are defined in `openflexure_microscope_server.things.camera` and `openflexure_microscope_server.things.stage` respectively. +All core functionality hardware control functionality is within `Thing` classes. Even the standard camera and stage classes are each a `Thing`. This means it is possible to use a different camera or stage by sub-classing the `BaseCamera` or `BaseStage` and editing the configuration file. diff --git a/apidocs/dev/config-file.md b/apidocs/dev/config-file.md index bbda452c..906aea83 100644 --- a/apidocs/dev/config-file.md +++ b/apidocs/dev/config-file.md @@ -1,6 +1,6 @@ # The Configuration File -By default, this configuration file is located at read from `/var/openflexure/settings/ofm_config.json` when the microscope is run as a service. If it is run at the command line, you should specify the configuration using the `-c` command line flag. +By default, this configuration file is read from `/var/openflexure/settings/ofm_config.json` when the microscope is run as a service. If it is run at the command line, you should specify the configuration file path using the `-c` command line flag. The default configuration file links to the configuration file in the repository: @@ -26,7 +26,7 @@ The configuration file has three keys: The `things` dictionary can specify a `Thing` to be loaded into the server in two different ways. If there is no custom configuration for the `Thing` then: -* The key is a **name** for the `Thing`, this defines the URL of its endpoints. +* The key is a **name** for the `Thing`, which defines the URL of its endpoints. * The value is the Python object reference for the `Thing`. For example: @@ -35,6 +35,8 @@ For example: "autofocus": "openflexure_microscope_server.things.autofocus:AutofocusThing", ``` +will add an autofocus Thing to the server. The Thing is located at `openflexure_microscope_server.things.autofocus:AutofocusThing`, (allowing multiple Things per Python file), and any endpoints (such as actions and properties) in that Thing will have the URL `base_url:port/autofocus/endpoint_name` + If further information needs to be supplied then the value should be a dictionary (Object) with the following keys: * `class` - *(Required)* The Python object reference for the `Thing`. diff --git a/apidocs/dev/ofm.css b/apidocs/dev/ofm.css index c60cc0ca..8fb64a72 100644 --- a/apidocs/dev/ofm.css +++ b/apidocs/dev/ofm.css @@ -833,7 +833,7 @@ body { border-radius: 2px; /*Approx the other side of the colour wheel from OFM pink.*/ color: #2fbf73; - /*Remove the padding and margin as it spaces in-line code to much from surrounding + /*Remove the padding and margin as it spaces in-line code too much from surrounding text and punctuation. */ margin: 0; diff --git a/apidocs/dev/python.md b/apidocs/dev/python.md index 955d0b5d..04caaab9 100644 --- a/apidocs/dev/python.md +++ b/apidocs/dev/python.md @@ -14,7 +14,7 @@ The server code is going through significant flux during the transition from v2 ## Python environment, build, and dependencies -As of `v3` we specify dependencies in `pyproject.toml`. These are not currently frozen due to difficulties matching versions on different platforms. On Raspberry Pi, it's best to specify `--only-binary=:all:` to ensure libraries like `numpy` and `scipy` are not compiled from source (which takes many hours, and/or fails). Pinning dependencies with `requirements.txt` and/or `requirements.in` may happen in the future. +As of `v3` we specify dependencies in `pyproject.toml`. These are not currently frozen due to difficulties matching versions on different platforms. On Raspberry Pi, it's best to specify `--only-binary=:all:` when installing packages, to ensure libraries like `numpy` and `scipy` are not compiled from source (which takes many hours, and/or fails). Pinning dependencies with `requirements.txt` and/or `requirements.in` may happen in the future. @@ -26,10 +26,10 @@ As of `v3` we specify dependencies in `pyproject.toml`. These are not currently **Before committing** you should lint and auto-format your code: -* To lint run `ruff check` +* To lint, run `ruff check` and manually fix any flagged issues * To auto-format the Python code run `ruff format` -**Before merging** please auto-format your code and also run the quality checks (linting, static analysis, and unit tests) +**Before pushing** please auto-format your code and also run the quality checks (linting, static analysis, and unit tests) * All commands above * `pytest` diff --git a/apidocs/dev/webapp.md b/apidocs/dev/webapp.md index 37516dbd..1d7d0fc2 100644 --- a/apidocs/dev/webapp.md +++ b/apidocs/dev/webapp.md @@ -31,5 +31,5 @@ When the development webapp starts it cannot locate the microscope API as this i To enforce code style we and quality we use ESLint and Prettier. Both can be run together with the same command. - To check the for errors and warnings run `npm run lint` -- To automatically fix errors an warnings run `npm run lint:fix` +- To automatically fix errors and warnings run `npm run lint:fix`