From 7de5eb8e204d02c7dbe1c55fe76f16c9e9abbee8 Mon Sep 17 00:00:00 2001 From: jupfi Date: Wed, 26 Jun 2024 21:39:48 +0200 Subject: [PATCH] Added development notes, updated README. --- README.md | 29 ++++ source/api_reference/quackseq.rst | 3 + source/index.md | 3 + source/installation.md | 11 ++ source/software_structure/development.md | 164 ++++++++++++++++++++++- 5 files changed, 207 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e69de29..a678f94 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,29 @@ +# NQRduckumentation + +Welcome to the NQRduckumentation - the central place for all documentation regarding the NQRduck software. + +This is obviously only the README file. The actual documentation is built using Sphinx. + +## Installation + +If for some reason you want to build the documentation yourself, you can do so by following these steps: + +1. Clone the repository: + +2. Install the required dependencies: + + ```bash + pip install -r requirements.txt + ``` + +3. Build the documentation: + + ```bash + make html + ``` + +4. Open the documentation found at `build/html/index.html` with your browser. + +## License + +The code itself is licensed under the MIT license. diff --git a/source/api_reference/quackseq.rst b/source/api_reference/quackseq.rst index 059ce8b..d772831 100644 --- a/source/api_reference/quackseq.rst +++ b/source/api_reference/quackseq.rst @@ -1,6 +1,9 @@ QuackSeq ======== +QuackSeq is a pulse programming framework for magnetic resonance spectroscopy experiments. +Sequences can bei either run on an Software Defined Radio (SDR) based spectrometer or simulated. + .. autosummary:: :toctree: _autosummary :recursive: diff --git a/source/index.md b/source/index.md index 4de4202..bd7ceaa 100644 --- a/source/index.md +++ b/source/index.md @@ -38,6 +38,9 @@ The core of the program is the nqrduck. It provides a central interface for comm The focus for spectrometers currently lies on LimeSDR based spectrometers (LimeSDR USB, LimeSDR Mini 2.0). +Additionally, the nqrduck framework has it's own modules for vendor independent control execution of pulse sequences. The pulse programming framework is called QuackSeq and a detailed documentation can be found [here](api_reference/quackseq.html). +Different QuackSeq sequences can either be executed on the LimeSDR or on a simulated spectrometer. + ```{toctree} :maxdepth: 1 :caption: Contents: diff --git a/source/installation.md b/source/installation.md index 7c15e38..d7e9612 100644 --- a/source/installation.md +++ b/source/installation.md @@ -31,3 +31,14 @@ 6. You now need to restart the program. 7. You can switch between different modules with the toolbar. You can customize the appearance of the program in `Settings -> Preferences`. Settings are saved and restored on the next start. +Some settings need a restart to take effect - so it's recommended to restart the program after changing settings. + +## Uninstall + +To uninstall the NQRduck, you can simply delete the virtual environment. If you additionally want the nqrduck package to remove any other files, you can run: + +```bash +nqrduck --uninstall +``` + +This removes the desktop file and the icon from the system. diff --git a/source/software_structure/development.md b/source/software_structure/development.md index 1165ffd..fdda5a4 100644 --- a/source/software_structure/development.md +++ b/source/software_structure/development.md @@ -1,9 +1,168 @@ # Development -This section describes the process of developing the NQRduck software. +This section describes the process of developing the NQRduck software. + +## Development of NQRduck modules + +Here, an exemplary workflow for the development of new NQRduck modules is given. + +If one wants to develop a new module, a template is provided [here](https://github.com/nqrduck/nqrduck-module). This template can be used as a starting point for a new module. + +For example, if one wants to develop a new module called *myduck*, one would first clone the repository. + +The template repository has the following file structure: + +```bash +nqrduck-module/ +|-- .gitignore +|-- LICENCE +|-- README.md +|-- pyproject.toml +|-- src/ +| |-- nqrduck_module/ +| | |-- __init__.py +| | |-- controller.py +| | |-- model.py +| | |-- module.py +| | |-- resources/ +| | | |-- module.ini +| | | |-- module_widget.ui +| | |-- view.py +| | |-- widget.py +``` + +*File structure of the NQRDuck module Git repository.* + +If one would now like to create a module with the example name *myduck*, the folder and file names would be modified in the following way: + +```bash +nqrduck-myduck/ +|-- .gitignore +|-- LICENCE +|-- README.md +|-- pyproject.toml +|-- src/ +| |-- nqrduck_myduck/ +| | |-- __init__.py +| | |-- controller.py +| | |-- model.py +| | |-- myduck.py +| | |-- resources/ +| | | |-- module.ini +| | | |-- myduck_widget.ui +| | |-- view.py +| | |-- widget.py + +``` + +*File structure of the newly created *myduck* module.* + +The class names inside the model, view, and controller classes should also be modified to have a more representative name (e.g., `MyDuckController`, `MyDuckView`, `MyDuckModel`). The object created in the `myduck` file should also be renamed: + +```python +from nqrduck.module.module import Module +from .model import MyDuckModel +from .view import MyDuckView +from .controller import MyDuckController + +MyDuck = Module(MyDuckModel, MyDuckView, MyDuckController) +``` + +Then the `.ini` file inside the resources folder should be modified to represent the *myduck* module. + +```toml +[META] +name = nqrduck-myduck +category = MyOwnModules +toolbar_name = MyDuck +tooltip = Template for a new module +``` + +*Example for the modified .ini file. The category, toolbar name, and tooltip can be freely chosen.* + +Additionally, the `pyproject.toml` has to be modified to represent the new module structure: + +```toml +[project] +name = "nqrduck-myduck" +version = "0.0.1" +authors = [ + { name="YOUR NAME", email="your@e.mail" }, +] + +description = "Your description" + +... + +dependencies = [ + "nqrduck", + "pyqt6", + ... +] + +[project.entry-points."nqrduck"] +"nqrduck-myduck" = "nqrduck_myduck.myduck:MyDuck" +``` + +Now functionality can be implemented. For example, the `myduck_widget.ui` could be modified using Qt Designer. The `widget.py` file can then be updated using `pyuic6`. + +```bash +# Navigate to the repository directory +cd nqrduck-myduck + +# Generate your widget.py +pyuic6 src/nqrduck_myduck/resources/myduck_widget.ui > src/nqrduck_myduck/widget.py +``` + +The module should be installed to test its functionality. Ideally, the module is installed with the `-e` argument of `pip` to install it in editable mode. This means changes in the source code of the project will be applied without reinstalling the module. + +```bash +# Navigate to the repository directory +cd nqrduck-myduck + +# Install the package and all dependencies +pip install -e . +``` + +## Example pyproject.toml + +```toml +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[project] +name = "nqrduck-module" +version = "0.0.1" +authors = [ + { name="Author Name", email="author@e.mail" }, +] + +description = "A template for nqrduck modules." +readme = "README.md" +license = { file="LICENSE" } +requires-python = ">=3.8" + +classifiers = [ + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", +] + +dependencies = [ + "matplotlib", + "pyqt6", + "nqrduck", +] + +[project.entry-points."nqrduck"] +"nqrduck-module" = "nqrduck_module.module:module" +``` ## Style +Here the style guide for the NQRduck software is described. + ### Linting Linting is done using [ruff](https://astral.sh/ruff) with the following configuration specified in the `pyproject.toml` file: @@ -44,7 +203,6 @@ Documentation is implemented with [Sphinx](https://www.sphinx-doc.org/en/master/ For docstrings in the code, the [Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) is used. - ## Branching The main branch is used for releases. Development is done on a development branch. Feature branches are created from the development branch and merged back into it. The development branch is merged into the main branch for releases. Releases are tagged with a version number starting with `v` (e.g. `v0.1.0`) and should follow [semantic versioning](https://semver.org/) (right now they don't). @@ -58,4 +216,4 @@ Right now the tests are not very extensive, but they are a good starting point f - The software is deployed via [PyPI](https://pypi.org/). Different modules are distributed as separate packages. The Action is run on a tag push to the main branch starting with `v` (e.g. `v0.1.0`). -- For Cython modules, `aarch64` and `x86_64` wheels are built using GitHub Actions. The wheels are deployed alongside the source distribution to PyPI. \ No newline at end of file +- For Cython modules, `aarch64` and `x86_64` wheels are built using GitHub Actions. The wheels are deployed alongside the source distribution to PyPI.