Merge pull request #8 from BAMresearch/4-add-documentation-page-on-how-to-use-the-app-with-screenshots-too

Add documentation page on how to use the app (with screenshots too)

Author: JosePizarro3

README.md

@@ -1,151 +1,60 @@
-# BAM Data Store: MasterDataChecker
+# Masterdata Checker
 
-The `masterdata_checker` is a Python package used to check the correctness of a given Masterdata definitions file with respect to the entities already registered in the BAM Data Store. The package provides a Graphical User Interface (GUI) on which the user can:
-- Choose a local Masterdata file to be checked.
+The `masterdata_checker` is a Django app used to check the correctness of a given Masterdata definitions file with respect to the entities already registered in the BAM Data Store (as defined in the [`bam-masterdata`](https://github.com/BAMresearch/bam-masterdata) package). In the app, you can:
+- Log in your openBIS instance.
+- Run checks of a local Masterdata Excel file. **Note**: only supported file formats are `.xls` and `.xlsx`
 - Revise the errors logs to correct mistakes in the original Masterdata file.
-- Depending on the credentials access, select a specific BAM Data Store instance and the Masterdata definitions therein.
 
-We also provide a Jupyter Notebook as a tutorial to execute the API of `masterdata_checker`.
-
-
-<!--
-## Getting started
-
- Add here installation instructions once the package is deployed -->
 
 ## Development
 
 If you want to develop locally this package, clone the project and enter in the workspace folder:
 ```sh
-git clone https://git.bam.de/bam-data-store/development/masterdata_checker.git
+git clone https://github.com/BAMresearch/masterdata-checker
 cd masterdata_checker
 ```
 
-Note you need to have installed the Python interface for the Tcl/Tk GUI toolkit ([`tkinter`](https://docs.python.org/3/library/tkinter.html)). If you don't have it, you can run:
-```sh
-sudo apt-get install python3-tk
-```
-
-#### Option 1: Virtual environment with `venv`
-
-Create a virtual environment (you can use Python>3.9) in your workspace:
-```sh
-python3 -m venv .venv
-source .venv/bin/activate
-```
-
-Make sure `pip` is upgraded:
-```sh
-pip install --upgrade pip
-```
-
-Install the package with the desired optional dependencies (specified in between brackets, e.g., `[dev]` or `[jupy]`) and in editable mode (with the added `-e` flag):
-```sh
-pip install -e '.[dev,jupy,docu]'
-```
-
-#### Option 2: `uv` virtual environment
-
 We recommend using `uv` for fast pip installation of the package. In this case, you can instead create a virtual environment by doing:
 ```sh
 uv venv
 source .venv/bin/activate
 ```
 
-Install the package with the desired optional dependencies (specified in between brackets, e.g., `[dev]` or `[jupy]`) and in editable mode (with the added `-e` flag):
+Install the package with the desired optional dependencies (specified in between brackets, e.g., `[dev]`) and in editable mode (with the added `-e` flag):
 ```sh
-uv pip install -e '.[dev,jupy,docu]'
+uv pip install -e '.[dev]'
 ```
 
-### Run the tests
+### Launch the Django app
 
-You can locally run the tests by doing:
+In order to launch the Django app, navigate to the `masterdata_checker/` subfolder:
 ```sh
-python -m pytest -sv tests
-```
-
-where the `-s` and `-v` options toggle the output verbosity.
-
-You can also generate a local coverage report:
-```sh
-python -m pytest --cov=src tests
-```
-
-### Run auto-formatting and linting
-
-We use [Ruff](https://docs.astral.sh/ruff/) for formatting and linting the code following the rules specified in the `pyproject.toml`. You can run locally:
-```sh
-ruff check .
-```
-
-This will produce an output with the specific issues found. In order to auto-fix them, run:
-```sh
-ruff format . --check
-```
-
-If some issues are not possible to fix automatically, you will need to visit the file and fix them by hand.
-
-<!-- ### Debugging
-
-For interactive debugging of the tests, use `pytest` with the `--pdb` flag. We recommend using an IDE for debugging, e.g., _VSCode_. If that is the case, add the following snippet to your `.vscode/launch.json`:
-```json
-{
-  "configurations": [
-      {
-        "name": "<descriptive tag>",
-        "type": "debugpy",
-        "request": "launch",
-        "cwd": "${workspaceFolder}",
-        "program": "${workspaceFolder}/.pyenv/bin/pytest",
-        "justMyCode": true,
-        "env": {
-            "_PYTEST_RAISE": "1"
-        },
-        "args": [
-            "-sv",
-            "--pdb",
-            "<path-to-plugin-tests>",
-        ]
-    }
-  ]
-}
+cd masterdata_checker
 ```
 
-where `<path-to-plugin-tests>` must be changed to the local path to the test module to be debugged.
-
-The settings configuration file `.vscode/settings.json` automatically applies the linting and formatting upon saving the modified file. -->
-
-### Documentation on Github pages
-
-To view the documentation locally, install the extra packages using:
+And run:
 ```sh
-uv pip install -e '[docu]'
+python manage.py runserver
 ```
 
-The first time, build the server:
+This will run the Django app server:
 ```sh
-mkdocs build
-```
+Performing system checks...
 
-Run the documentation server:
-```sh
-mkdocs serve
+System check identified no issues (0 silenced).
+June 05, 2025 - 06:24:20
+Django version 5.2.1, using settings 'checker.settings'
+Starting development server at http://127.0.0.1:8000/
+Quit the server with CONTROL-C.
 ```
 
-The output looks like:
-```sh
-INFO    -  Building documentation...
-INFO    -  Cleaning site directory
-INFO    -  [14:07:47] Watching paths for changes: 'docs', 'mkdocs.yml'
-INFO    -  [14:07:47] Serving on http://127.0.0.1:8000/
-```
+Simply click on the localhost address `http://127.0.0.1:8000/` to launch the app.
 
-Simply click on `http://127.0.0.1:8000/`. The changes in the `md` files of the documentation are inmediately reflected when the files are saved (the local web will automatically refresh).
 
 ## Main contributors
 
 | Name | E-mail     | Role |
-|------|------------|--------|-----------------|
+|------|------------|--------|
 | Carlos Madariaga | [[email protected]]([email protected]) | Admin |
 | Dr. Jose M. Pizarro | [[email protected]]([email protected]) | Maintainer |
 | Jörg Rädler | [[email protected]]([email protected]) | Maintainer |

pyproject.toml

@@ -14,10 +14,10 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
 ]
 name = "masterdata-checker"
-description = "A Python tool to check the correctness of a given Masterdata definitions file with respect to the entities already registered in the BAM Data Store."
+description = "A Django app to check the correctness of a Masterdata definitions file with respect to the entities already registered in an openBIS instance."
 dynamic = ["version"]
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [
   { name = "Carlos Madariaga", email = "[email protected]" },
   { name = "Jose M. Pizarro", email = "[email protected]" },
@@ -49,9 +49,6 @@ dev = [
   "structlog==24.4.0",
 ]
 
-[project.scripts]
-masterdata_checker = "masterdata_checker.cli:cli"
-
 [tool.ruff]
 # Exclude a variety of commonly ignored directories.
 include = ["masterdata_checker/*.py", "tests/*.py"]