Merge branch 'dev' into 'main'

Update documentation and version number

Closes #75

See merge request !27

.gitlab-ci.yml

@@ -64,7 +64,7 @@ test:
 pages:
   stage: docs
   script:
-  - pip install -U sphinx sphinx-autoapi sphinx_rtd_theme # sphinx_panels
+  - pip install -U sphinx sphinx-autoapi sphinx_rtd_theme myst-parser # sphinx_panels
   - cd docs
   - make html
   - mv build/html/ ../public

README.md

@@ -25,7 +25,7 @@ venv\Scripts\Activate.ps1 # Windows PowerShell
 
 ### From PyPi with pip
 2. Install plotID  
-`pip install plotid --extra-index-url=https://test.pypi.org/simple/`  
+`pip install plotid`  
 If you also want to run the unittests use `plotid[test]` instead of `plotid`.
 
 ### From source
@@ -50,7 +50,7 @@ The argument "plot_engine" defines which plot engine was used to create the figu
 - 'matplotlib', which processes figures created by matplotlib.
 - 'image', which processes pictures with common extensions (jpg, png, etc.).
 
-tagplot returns a list that contains two lists each with as many entries as figures were given. The first list contains the tagged figures. The second list contains the corresponding IDs as strings
+tagplot returns a PlotIDTransfer object that contains the tagged figures and the corresponding IDs as strings.
 
 Optional parameters can be used to customize the tag process.
 - prefix : str, optional
@@ -59,23 +59,25 @@ Optional parameters can be used to customize the tag process.
         id_method for creating the ID. Create an ID by Unix time is referenced as 'time', create a random ID with id_method='random'. The default is 'time'.
 - location : string, optional
         Location for ID to be displayed on the plot. Default is 'east'.
+- qrcode : boolean, optional
+        Experimental support for encoding the ID in a QR Code.
 
 Example:  
 ```python
 FIG1 = plt.figure()  
 FIG2 = plt.figure()   
 FIGS_AS_LIST = [FIG1, FIG2]  
-[TAGGED_FIGS, ID] = tagplot(FIGS_AS_LIST, 'matplotlib', prefix='XY23_', id_method='random', location='west')
+FIGS_AND_IDS = tagplot(FIGS_AS_LIST, 'matplotlib', prefix='XY23_', id_method='random', location='west')
 ```
 
 
 ### publish()
 Save plot, data and measuring script. It is possible to export multiple figures at once.
-`publish(src_datapath, dst_path, figure, plot_name)`
-
+`publish(figs_and_ids, src_datapath, dst_path, plot_name)`  
+  
+- "figs_and_ids" must be a PlotIDTransfer object. Therefore, it can be directly passed from tagplot() to publish().  
 - "src_datapath" specifies the path to (raw) data that should be published. It can be a string or a list of strings that specifies all files and directories which will be published.  
 - "dst_path" is the path to the destination directory, where all the data should be copied/exported to.  
-- "figure" expects the figure or a list of figures that were tagged and now should be saved as pictures. If image files were tagged, all of them need to have the same file extension.  
 - "plot_names" will be the file names for the exported plots. If you give only one plot name but several figures, plotID will name the exported plots with an appended number, e.g. example_fig1.png, example_fig2.png, ...  
 
 Optional parameters can be used to customize the publish process.
@@ -84,7 +86,7 @@ Optional parameters can be used to customize the publish process.
   - centralized: The raw data will copied only once. All other plots will reference this data via sym link.
   - individual: The complete raw data will be copied to a folder for every plot, respectively.
 Example:
-`publish('/home/user/Documents/research_data', '/home/user/Documents/exported_data', FIG1, 'EnergyOverTime-Plot')`  
+`publish(figs_and_ids, '/home/user/Documents/research_data', '/home/user/Documents/exported_data', 'EnergyOverTime-Plot')`  
 
 ## Build
 If you want to build plotID yourself, follow these steps:  
@@ -100,4 +102,4 @@ If you want to build plotID yourself, follow these steps:
 
 ## Documentation
 If you have more questions about plotID, please have a look at the [documentation](https://plotid.pages.rwth-aachen.de/plotid_python).  
-Also have a look at the [example.py](plotid/example.py) that is shipped with plotID.
+Also have a look at the [examples](./examples) that are shipped with plotID.

docs/source/conf.py

@@ -36,7 +36,8 @@ release = __version__
 # ones.
 extensions = [
     'sphinx.ext.napoleon',
-    'autoapi.extension'
+    'autoapi.extension',
+    "myst_parser"
 ]
 autoapi_type = 'python'
 autoapi_dirs = ['../../plotid', '../../tests']

docs/source/index.rst

@@ -10,6 +10,8 @@ Welcome to PlotID's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+    README <readme_link.rst>
+
 
 Indices and tables
 ==================

docs/source/readme_link.rst

+Readme File
+-----------
+
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
\ No newline at end of file

plotid/__init__.py

@@ -10,5 +10,5 @@ research data, the plot is based on. Additionally, the script that created the
 plot will also be copied to the directory.
 """
 
-__version__ = '0.1.2'
+__version__ = '0.2.1'
 __author__ = 'Institut Fluidsystemtechnik within nfdi4ing at TU Darmstadt'

plotid/tagplot.py

@@ -42,6 +42,8 @@ def tagplot(figs, engine, location='east', **kwargs):
         id_method for creating the ID. Create an ID by Unix time is referenced
         as 'time', create a random ID with id_method='random'.
         The default is 'time'.
+    qcode : boolean, optional
+        Experimental support for encoding the ID in a QR Code.
 
     Raises
     ------

setup.cfg

@@ -28,9 +28,13 @@ install_requires =
     Pillow
     matplotlib
     numpy
+    qrcode
    
 [options.extras_require]
 test =
     coverage
-
-
+docs =
+    sphinx
+    sphinx-autoapi
+    sphinx-rtd-theme
+    myst-parser