Skip to content
Snippets Groups Projects
Commit 10ecc7c8 authored by Mayr, Hannes's avatar Mayr, Hannes
Browse files

Improve readme and contributing documentation.

parent 72d1285b
No related branches found
No related tags found
1 merge request!33Improve readme and contributing documentation.
Pipeline #813355 waiting for manual action
## Implement a new plot engine
If you want to add another plot engine "$engine" to plotID, this document helps you to do it.
# Contributing
Feel free to **report** all **issues** you encounter with plotID in our [issue tracker](https://git.rwth-aachen.de/plotid/plotid_python/-/issues). This will greatly help to improve plotID.
Contributing to plotID via **merge requests** is also highly appreciated. Please make sure that your code complies with the [PEP 8 - Style Guide](https://peps.python.org/pep-0008/) before creating a merge request. We try to have the whole code of plotID covered by unittests. So if you contribute new code to plotid please also provide unittests that cover the new functionality. Should you be interested in adding another plot engine to be supported by plotID, have a look at the section [Implement a new plot engine](#add-plot-engine). There are some hints how to proceed in this case.
## Setup development environment
Clone the repository and install the dependencies:
```bash
git clone https://git.rwth-aachen.de/plotid/plotid_python.git
cd plotid_python
pip install -r requirements.txt
```
Optionally, create a virtual environment as recommended in the [README.md](https://git.rwth-aachen.de/plotid/plotid_python/-/blob/main/README.md).
You can run all the unittests locally by calling the *tests/runner_tests.py* script. For linting we recommend using *flake8* and *pylint*.
The documentation is automatically built from docstrings in the code. So always document your code properly. The documentation can be built locally and can be found afterwards in *docs/build*:
```bash
cd docs
make html
```
## Implement a new plot engine {#add-plot-engine}
If you want to add another plot engine "$engine" to plotID, this section helps you to do it. For comparison have a look at already supported engines, e.g. in tagplot_matplotlib.py or tagplot_image.py.
### tagplot
Create a new module named "tagplot_$engine.py". Paste the following code and replace every "$engine" with the name of your engine:
......@@ -8,11 +27,11 @@ Create a new module named "tagplot_$engine.py". Paste the following code and rep
Tag your picture with an ID.
Functions:
tagplot_$engine(PlotOptions instance) -> list
tagplot_$engine(PlotOptions instance) -> PlotIDTransfer instance
"""
import $engine
from plotid.create_id import create_id
from plotid.plotoptions import PlotOptions
from plotid.plotoptions import PlotOptions, PlotIDTransfer
def tagplot_$engine(plotid_object):
......@@ -21,32 +40,44 @@ def tagplot_$engine(plotid_object):
The ID is placed visual on the figure window and returned as string in a
list together with the figures.
TagPlot can tag multiple figures at once.
Parameters
----------
plotid_object : instance of PlotOptions
Returns
-------
PlotIDTransfer object
"""
# Check if plotid_object is a valid instance of PlotOptions
if not isinstance(plotid_object, PlotOptions):
raise TypeError('The given options container is not an instance'
'of PlotOptions.')
ids_as_list = []
# Check if figs is a list of valid figures
for figure in plotid_object.figs:
if not isinstance(figure, $engine_figure_class):
raise TypeError('Figure is not a valid $engine-figure.')
# Loop to create and position the IDs
for fig in plotid_object.figs:
figure_id = create_id(plotid_object.id_method)
ids_as_list.append(figure_id)
fig_id = create_id(plotid_object.id_method)
fig_id = plotid_object.prefix + fig_id
plotid_object.figure_ids.append(fig_id)
"""
Insert here the tagging with $engine:
Open the figure fig.
Place the string figure_id on it.
Use plotid_object.position and plotid_object.rotation for position and rotation.
Use plotid_object.position and plotid_object.rotation for position and rotation of the ID.
Save the tagged figure to plotid_object.figs.
"""
return [plotid_object.figs, ids_as_list]
figs_and_ids = PlotIDTransfer(plotid_object.figs, plotid_object.figure_ids)
return figs_and_ids
```
Last step:
Add the following code in tagplot.py:
```python
match engine:
[...]
case '$engine':
......@@ -60,7 +91,7 @@ To include a new plot engine in the publish function only save_plot.py has to be
Import the plot engine at the top of the file.
In the beginning of the function save_plot() create the following line:
```python
if isinstance(figures, $type_of_figure):
if isinstance(figures, $engine_figure_class):
figures = [figures]
[...]
if not isinstance(figures, list):
......@@ -77,3 +108,5 @@ for i, fig in enumerate(figures):
plot_path.append(plot_names[i] + '.' + extension)
# Save the figure fig to plot_path[i]
```
Additionally, please add some unittests for your code inside the *tests* directory.
In the end, you can also include a simple example in the *examples* directory how the newly plot engine can be used with plotID.
\ No newline at end of file
......@@ -8,7 +8,7 @@ plotID is a program connected to Research Data Management (RDM). It has two main
**Note:** To run plotID python version ≥ 3.10 is required.
## Installation
Currently there are two options to run plotID. Either install it via pip from the Python Package Index (PyPi) or install plotID from the source code.
Currently there are two options to run plotID. Either install it via pip from the Python Package Index (PyPi) or install plotID from the source code. Apart from setting up an optional virtual environment, installation is the same for Windows and Unix systems.
1. [Optional] Create a virtual environment and activate it:
```bash
......@@ -99,6 +99,9 @@ If you want to build plotID yourself, follow these steps:
4. Build the package
`python3 -m build`
## Contributing
Contributions to plotID are very welcome. If you encounter any issues with plotID please report them in our [issue tracker](https://git.rwth-aachen.de/plotid/plotid_python/-/issues). Code contributions via merge request are also highly appreciated. Please have a look at [CONTRIBUTING](https://git.rwth-aachen.de/plotid/plotid_python/-/blob/main/CONTRIBUTING.md) first.
## Documentation
If you have more questions about plotID, please have a look at the [documentation](https://plotid.pages.rwth-aachen.de/plotid_python).
......
......@@ -3,7 +3,7 @@
Tag your picture with an ID.
Functions:
tagplot_image(PlotOptions instance) -> list
tagplot_image(PlotOptions instance) -> PlotIDTransfer instance
"""
import os
from PIL import Image, ImageDraw, ImageFont, ImageOps
......
......@@ -3,7 +3,7 @@
Tag your matplotlib plot with an ID.
Functions:
tagplot_matplotlib(PlotOptions instance) -> list
tagplot_matplotlib(PlotOptions instance) -> PlotIDTransfer instance
"""
import matplotlib
......
......@@ -3,10 +3,14 @@ cycler==0.11.0
fonttools==4.32.0
kiwisolver==1.4.2
matplotlib==3.5.2
myst-parser==0.18.0
numpy==1.22.3
packaging==21.3
Pillow==9.2.0
Pillow==9.1.0
pyparsing==3.0.8
python-dateutil==2.8.2
qrcode==7.3.1
six==1.16.0
Sphinx==5.0.2
sphinx-autoapi==1.8.4
sphinx-rtd-theme==1.0.0
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment