rahix/openflexure-microscope-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'jtc42-master-patch-34988' into 'master'

Browse source 
Added better developer notes

See merge request openflexure/openflexure-microscope-server!88
This commit is contained in:
Joel Collins 2020-11-19 12:11:25 +00:00
commit 43931723d4
1 changed files with 32 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

61
README.md
View file

@ -8,15 +8,39 @@ This includes basic installation instructions suitable for most users.
Full developer documentation can be found on [**ReadTheDocs**](https://openflexure-microscope-software.readthedocs.io/).
This includes installing the server in a mode better suited for active development.
## Developer installation
# Developer guidelines
## Installation
* `git clone https://gitlab.com/openflexure/openflexure-microscope-server.git`
* `poetry install`
* `poetry run build_static`
* Building the static interface will require a valid Node.js installation
* To build on a Raspberry Pi:
* `curl -sL https://deb.nodesource.com/setup_14.x | sudo bash -`
* `sudo apt install nodejs`
## Formatting and linting
We use 3 main code analysis and formatting libraries in this project. **Please run all of these before submitting a merge request.**
Our CI will check each of these automatically, so ensuring they pass locally will save you time.
* **Black** - Code formatting with minimal configuration.
* While sometimes it's not perfect, its fine 90% of the time and prevents arguments about formatting.
* Automatically formats your code
* `poetry run black .`
* **Isort** - Import sorting
* Automatically organises your imports to stop things getting out of hand
* `poetry run isort .`
* **Pylint** - Static code analysis
* Analyses your code, failing if issues are detected.
* We've disabled some less severe warnings, so _if anything fails your merge request will be blocked_
* `poetry run pylint openflexure_microscope`
### Pre-commit hooks
We make use of pre-commit hooks to run code analysis before committing to the codebase.
We support pre-commit hooks to run code formatting before committing to the codebase.
The simplest way to ensure this works is to install pre-commits into your current Python environment:
@ -25,42 +49,21 @@ The simplest way to ensure this works is to install pre-commits into your curren
To run pre-commit analysis manually, you can run `pre-commit run`.
### Node installation
* Note, building the static interface will require a valid Node.js installation
* To build on a Raspberry Pi:
* `curl -sL https://deb.nodesource.com/setup_14.x | sudo bash -`
* `sudo apt install nodejs`
### Distributing
* `mkdir -p dist`
* `tar -c --exclude-vcs --exclude-from .tarignore -vzf dist/openflexure-microscope-server.tar.gz .`
#### Docker
We don't use docker to distribute the server application due to the number of system-level permissions it would need, and the fact that docker mounts break the autostorage extension. If you really want to use docker though, after building the image on your pi you need to start the container with the following flags:
* `docker run --privileged -v /opt/vc:/opt/vc --env LD_LIBRARY_PATH=/opt/vc/lib --device /dev/vchiq --publish 5000:5000`
## Build-system
As of 1.0.0b0, we're using [Poetry](https://github.com/sdispater/poetry) to manage dependencies, build, and distribute the package. All package information and dependencies are found in `pyproject.toml`, in line with [PEP 518](https://www.python.org/dev/peps/pep-0518/). If you're developing this package, make use of `poetry.lock` to ensure you're using the latest locked dependency list.
## Microscope plugins
## Microscope extensions
The Microscope module, and Flask app, both support plugins for extending lower-level functionality not well suited to web API calls.
This plugin system is still in fairly early development, and is not yet properly documented. The current documentation can be found [here](https://openflexure-microscope-software.readthedocs.io/en/latest/plugins.html).
The Microscope module, and Flask app, both support plugins for extending lower-level functionality not well suited to web API calls. The current documentation can be found [here](https://openflexure-microscope-software.readthedocs.io/en/latest/plugins.html).
## Running tests through the PTVSD remote debugger (port 3000)
# Credits
* From the openflexure-microscope-software directory, run `python3 -m ptvsd --host 0.0.0.0 --port 3000 --wait tests/test_camera.py`
## Credits
### Piexif
## Piexif
The microscope server includes a forked copy of hMatoba's [Piexif](https://github.com/hMatoba/Piexif), licensed under the MIT License.
### Video streaming
## Video streaming
Based on supporting code for the article [video streaming with Flask](http://blog.miguelgrinberg.com/post/video-streaming-with-flask) and its follow-up [Flask Video Streaming Revisited](http://blog.miguelgrinberg.com/post/flask-video-streaming-revisited).
Camera streaming was initially based on supporting code for the article [video streaming with Flask](http://blog.miguelgrinberg.com/post/video-streaming-with-flask) and its follow-up [Flask Video Streaming Revisited](http://blog.miguelgrinberg.com/post/flask-video-streaming-revisited).