Update readme

README.md

@@ -39,17 +39,148 @@ At least this repo will help to bring alife some good things and will show hidde
 * some extensions require custom Python installation/modules. See documentation at our FabLab Chemnitz Wiki (see below).
 * some extensions require additional commands, packages or other installers (see documentation too).
 
-# Installation way 1: with git dependencies
+# Structure
 
-The structure of this repo is intended the be easy. Just copy the complete MightyScape folder or the folders you want to your Inkscape's extension directory. You will find redundancies in this repo like node.exe (NodeJS). We did it this way to give easy possibilty to only pick the extensions you want (instead creating hundreds of repositories). MightyScape does not work with any releases or feature branches. Just use "git clone" to get the recent commit from master branch. Please see at https://y.stadtfabrikanten.org/mightyscape-overview for installation tips like required python modules, file locations and other adjustments.
+The structure of this repo is intended the be easy. Just copy the complete MightyScape folder (or the particular folders you want) to your Inkscape's extension directory. You will find redundancies in this repo like node.exe (NodeJS). We did it this way to give easy possibilty to only pick the extensions you want. MightyScape does not work with any releases or feature branches.
 
-# Installation way 2: with zip archives (mirrors)
+# Installation
+
+Please read this first before opening issues! This documentation does not maintain any progressive information about installing or handling Inkscape itself.
+
+## Unsupported Inkscape versions
+
+MightyScape **does not support the snap version** and also **no** **[AppImage]([https://inkscape.org/release/inkscape-dev/gnulinux/appimage/dl](https://inkscape.org/release/inkscape-dev/gnulinux/appimage/dl/))** version of Inkscape. The snap edition comes with restrictions, letting a lot of extensions fail to work. The reason is missing access to external python interpreter.s Libraries like openmesh or pyclipper cannot be used this way. The AppImage version will fail for a lot extension too, because subprocesses from the AppImage have no acccess to `/tmp `directory. You can still install MightyScape with snap or AppImage version but beware to get different errors. Feel free to contribute solutions to fix these issues.
+
+### Supported Inkscape versions
+
+MightyScape supports
+
+- Windows
+  
+  - Inkscape portable (from zip or tar.gz)
+  
+  - regular installation with MSI Setup
+
+- Linux
+  
+  - regular installation from package manager like dnf/yum or apt
+    
+    `sudo apt install inkscape #Ubuntu`
+    `sudo dnf install inkscape #Fedora`
+
+- MacOS
+  
+  - this was never tested. We are sorry!
+
+## Installation of prerequisites - python interpreter
+
+MightyScape relies on the Python interpreter which is used by the OS. As we need to install some external dependencies (python modules, partially with C bindings), we cannot rely on the bundled Python version, which comes with Inkscape. For this reason we need to adjust the main configuration of inkscape to apply this change.
+**Note:** Using a custom Python environment on Windows wil make the official Inkscape Extensions Manager impossible to run. The reason is the library `pygobject`.
+
+**On Linux this might look like:**
+
+```
+vim ~/.config/inkscape/preferences.xml
+```
+
+Add the following line in the section id="extensions":
+
+```
+  <group
+     id="extensions"
+     python-interpreter="/usr/bin/python"
+```
+
+**On Windows this might look like:**
+
+```
+notepad %appdata%\inkscape\preferences.xml
+```
+
+```
+  <group
+     id="extensions"
+     python-interpreter="C:\Users\youruser\AppData\Local\Programs\Python\Python310\pythonw.exe"
+```
+
+**Notes for Windows users:** 
+
+* If you get a nasty popup window each time you are executing an extension, please check if you really use pythonw.exe. Do not use python.exe.
+* You can download and install Python for Windows from https://www.python.org/downloads/windows
+* please double check for the correct enviroment variable adjustment. python.exe has to be in `%PATH%`
+
+## Installation of prerequisites - additional python modules
+
+The following extra libraries are required for some of the extensions within the MightyScape package. Those are listed in our [requirements.txt](https://gitea.fablabchemnitz.de/FabLab_Chemnitz/mightyscape-1.2/requirements.txt) file. We are installing them together with MightyScape in the next section.
+
+
+**Note:** if openmesh fails to install, please see [Paperfold](https://stadtfabrikanten.org/display/IFM/Paperfold) for more details about installing it
+
+## Installation dirs
+
+There are two places where Inkscape extensions can be located by default, either install (global) directory or user directory. We usually put the extensions in the user's data directories directory, because if we would put it to the installation folder of Inkscape, we would risk deletion by upgrading. If we put them to the user directory we do not lose them.
+
+| OS                     | user directory                   | global directory                        |
+| ---------------------- | -------------------------------- | --------------------------------------- |
+| Linux (Ubuntu, Fedora) | `~/.config/inkscape/extensions/` | `/usr/share/inkscape/extensions/`       |
+| Windows                | `%AppData%\inkscape\extensions\` | `C:\Program Files\inkscape\extensions\` |
+
+## Installation way 1: with git dependencies (preferred way)
+
+**On Linux this might look like:**
+
+```
+dnf install python3-devel #this might be required on Fedora
+cd  ~/.config/inkscape/extensions/
+git clone https://gitea.fablabchemnitz.de/FabLab_Chemnitz/mightyscape-1.2.git
+```
+
+**On Windows this might look like:**
+
+```
+cd %AppData%\inkscape\extensions\
+git clone https://gitea.fablabchemnitz.de/FabLab_Chemnitz/mightyscape-1.2.git
+cd %AppData%\..\Local\Programs\Python\Python310\Scripts
+python -m pip install --upgrade pip #upgrade pip first
+pip install --upgrade  --quiet --no-cache-dir -r %AppData%\inkscape\extensions\requirements.txt
+```
+
+**Note about git handling**: You can also download the whole git project as .zip or .tar.gz bundled archive and then place it to your target directory. This way you can ignore installing git on your system yet. You can convert that directory to the git-way using the [upgrade extension]([mightyscape-1.2/about_upgrade_mightyscape an master - mightyscape-1.2 - FabLab Chemnitz - Gitea: Git with a cup of tea](https://gitea.fablabchemnitz.de/FabLab_Chemnitz/mightyscape-1.2/src/branch/master/extensions/fablabchemnitz/about_upgrade_mightyscape)) later on.
+ <img title="" src="./docs/images/zip-download.png" alt="" data-align="left">
+
+## Installation way 2: with zip archives (mirrors)
 
 If you only want to download single parts of MightyScape, use one of the following mirrors:
 
 * https://gitea.fablabchemnitz.de/FabLab_Chemnitz/mightyscape-1.2-zipmirror
 * https://github.com/eridur-de/mightyscape-1.2-zipmirror
 
+You can put the extracted files into your local or global Inkscape extension directory. Please refer to the [official documentation](https://inkscape-manuals.readthedocs.io/en/latest/extensions.html#installing-extensions).
+
+## ## Upgrading MightyScape
+
+There are two ways to upgrade MightyScape. Choose from:
+
+1. if you installed MightyScape using git clone, just go to the git directory and run `git pull` or use the extension "Upgrade MightyScape", which can be found in Extensions → FabLab Chemnitz → Upgrade MightyScape
+   - There is some special updater extension which allows to update the complete MightyScape package once it was properly pulled by git. You need to install `GitPython` library to use the updater:
+<img title="" src="./docs/images/upgrade-extension.png" alt="" data-align="left">
+
+2. if you previously downloaded a bulk zip file from github or gitea, just replace the content of the containing folder with the new files
+
+## Upgrading Python modules
+
+Sometimes it can help to upgrade python modules. This section shows some useful shell lines (**but be warned to use them on your own risk**):
+
+```
+pip list --outdated
+
+#Linux: 
+pip list --outdated --format=freeze | grep -v '^\-e' | cut -d = -f 1  | xargs -n1 pip install -U 
+
+#Windows: 
+for /F "delims= " %i in ('pip list --outdated') do pip install -U %i
+```
+
 # Issues, questions, documentation, examples
 
 This repo has two remotes:

requirements.txt

@@ -0,0 +1,35 @@
+debugpy
+lxml
+moderngl
+numpy
+networkx 
+openmesh
+opencv-python
+pyclipper
+pillow 
+scipy 
+scour 
+shapely 
+svg-to-gcode 
+svgpathtools 
+vpype 
+vpype-dxf 
+GitPython #required by mightyscape updater extension
+wheel 
+pytesseract
+cairosvg
+PyQt5
+PySide6
+brother_ql #required by iventory_sticker extension
+cssselect #required by boxes.py and mightyscape updater extension
+affine #required by boxes.py extension
+
+#vpype occult plugin setup
+git+https://github.com/abey79/occult.git#egg=occult
+
+#vpype deduplicate plugin setup
+tqdm
+git+https://github.com/LoicGoulefert/deduplicate.git#egg=deduplicate
+
+#plycutter
+git+https://github.com/tjltjl/plycutter.git