From b78c5f2a1fd5d78abfa49a8164d736f1384d190d Mon Sep 17 00:00:00 2001
From: "Mayr, Hannes" <hannes.mayr@stud.tu-darmstadt.de>
Date: Wed, 21 Sep 2022 16:45:14 +0200
Subject: [PATCH] Update documentation and version number

---
 .gitlab-ci.yml              |  2 +-
 README.md                   | 18 ++++++++++--------
 docs/source/conf.py         |  3 ++-
 docs/source/index.rst       |  2 ++
 docs/source/readme_link.rst |  5 +++++
 plotid/__init__.py          |  2 +-
 plotid/tagplot.py           |  2 ++
 setup.cfg                   |  8 ++++++--
 8 files changed, 29 insertions(+), 13 deletions(-)
 create mode 100644 docs/source/readme_link.rst

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 3972355..27acee3 100644
--- a/.gitlab-ci.yml
+++ b/.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
diff --git a/README.md b/README.md
index 1695685..1c1b247 100644
--- a/README.md
+++ b/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.
diff --git a/docs/source/conf.py b/docs/source/conf.py
index fe798ee..a866324 100644
--- a/docs/source/conf.py
+++ b/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']
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 34d0792..925e89d 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -10,6 +10,8 @@ Welcome to PlotID's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+    README <readme_link.rst>
+
 
 Indices and tables
 ==================
diff --git a/docs/source/readme_link.rst b/docs/source/readme_link.rst
new file mode 100644
index 0000000..5b96f4d
--- /dev/null
+++ b/docs/source/readme_link.rst
@@ -0,0 +1,5 @@
+Readme File
+-----------
+
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
\ No newline at end of file
diff --git a/plotid/__init__.py b/plotid/__init__.py
index b9b886c..306280a 100644
--- a/plotid/__init__.py
+++ b/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'
diff --git a/plotid/tagplot.py b/plotid/tagplot.py
index 41d4ae6..b0f365e 100644
--- a/plotid/tagplot.py
+++ b/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
     ------
diff --git a/setup.cfg b/setup.cfg
index 5abba63..dcda034 100644
--- a/setup.cfg
+++ b/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
-- 
GitLab