[FEATURE] Introduce PyPI setup to distribute python package

.github/CONTRIBUTING.md

@@ -9,8 +9,11 @@
     - [Squash Commit Summary](#squash-commit-summary)
 - [Release](#release)
   - [Automatic CHANGELOG creation](#automatic-changelog-creation)
+  - [PyPI commands](#pypi-commands)
 - [Structure of the repository](#structure-of-the-repository)
+- [User directory](#user-directory)
 - [Anaconda environment](#anaconda-environment)
+- [Other command](#other-command)
 
 ## How to Contribute
 1. Create a branch by forking the repository and apply your change.
@@ -73,15 +76,31 @@ To generate the CHANGELOG.md for a upcoming release (no tag exists yet), the fol
 git-chglog -o CHANGELOG.md --next-tag v0.10.0
 ```
 
+### PyPI commands
+1. Change the version in setup.cfg and gdal-user.yml
+2. Build a new release to publish to PyPI:  
+```
+py -m build
+```
+3. Publish these files to PyPI:  
+```
+twine upload dist\*
+```
+
 ## Structure of the repository
 There is one python coding base for both Windows and for macOS.
 Differences between the different OS are the used programs.
 The folders in the repo have the following purposes:
-- common_download - all downloaded files are saved and extracted here
-- common_python - custom python files
-- common_resources - config, json files
-- tooling - programs, scripts used by Windows and macOS
-- tooling_win - programs, scripts for Windows
+- `wahoo_mc` - custom python files
+- `wahoo_mc/resources` - config, json files
+- `wahoo_mc/tooling_win` - programs, scripts for Windows
+- `tooling` - programs, scripts used by Windows and macOS to test and check the generated maps
+
+## User directory
+Files which are processed through the tool are stored in the user directory to be release-independent. The name of the directory is: `$user_directory/wahooMapsCreatorData` and has the follwing folders:
+- root - generated files are saved here
+- `_download` - all downloaded files are saved and extracted here
+- `_tiles` - intermediate files per tile are stored here
 
 ## Anaconda environment
 - /conda_env/gdal-user.yml is for creating Anaconda environment for users
@@ -99,4 +118,10 @@ conda env export > environment.yml
 
 The installation of Anaconda envirionments is described [here](docs/QUICKSTART_ANACONDA.md)
 
-more information on [documentation for sharing Anaconda environments](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#exporting-an-environment-file-across-platforms)
+more information on [documentation for sharing Anaconda environments](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#exporting-an-environment-file-across-platforms)
+
+## Other command
+Run pylint for all relevant directories/files
+```
+pylint -j 0 ./wahoomc ./tests  
+```

.github/workflows/tests.yml

@@ -10,18 +10,18 @@ jobs:
       matrix:
         python-version: ["3.9", "3.10"]
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v3
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install pylint
-        pip install mock
-        pip install requests
-    - name: Analysing the code with pylint
-      run: |
-        pylint -j 0 ./wahoo_mc ./tests
-      continue-on-error: false
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pylint
+          pip install mock
+          pip install requests
+      - name: Analysing the code with pylint
+        run: |
+          pylint -j 0 ./wahoomc ./tests
+        continue-on-error: false

.gitignore

@@ -4,8 +4,6 @@
 /!.vscode/settings.json
 
 # top level
-/dist
-/envs
 osmconvert_tempfile.*
 
 # in all folders
@@ -17,4 +15,11 @@ osmconvert_tempfile.*
 # mac/unix
 
 #windows
-/wahoo_mc/tooling_win/osmconvert_tempfile.*
+/wahoomc/tooling_win/osmconvert_tempfile.*
+
+# build artefacts
+*.pyc
+.eggs/
+/wahoomc.egg-info/
+/dist/
+/build/

README.md

@@ -38,11 +38,11 @@ conda activate gdal-user
 ```
 Run wahooMapsCreator via GUI
 ```
-python -m wahoo_mc gui
+python -m wahoomc gui
 ```
 Or run wahooMapsCreator via CLI
 ```
-python -m wahoo_mc cli -co malta
+python -m wahoomc cli -co malta
 ```
 
 A detailled description of the usage is documented [:computer: here](docs/USAGE.md#usage-of-wahoomapscreator)

conda_env/gdal-dev.yml

@@ -9,3 +9,8 @@ dependencies:
   - geojson=2.5.*
   - shapely=1.8.*
   - autopep8=1.6.*
+  - mock
+  - twine
+  - pip
+  - pip:
+      - build

conda_env/gdal-user.yml

@@ -5,5 +5,6 @@ dependencies:
   - python=3.7
   - geojson=2.5.*
   - gdal=3.4.*
-  - requests=2.27.*
-  - shapely=1.8.*
+  - pip
+  - pip:
+      - wahoomc==2.0.0a5

copyFilesToDist.sh

@@ -20,19 +20,19 @@ cd ../..
 cd dist/${FOLDER_NAME_MAC}
 
 # create empty sub-folders
-mkdir -p ./wahoo_mc
-mkdir -p ./wahoo_mc/resources
+mkdir -p ./wahoomc
+mkdir -p ./wahoomc/resources
 mkdir -p ./conda_env
 mkdir -p ./tooling
 mkdir -p ./docs
 
 # copy files into dist-folder
-cp -a ../../wahoo_mc/*.py ./wahoo_mc/
-cp -a ../../wahoo_mc/resources/*.xml ./wahoo_mc/resources/
-cp -a ../../wahoo_mc/resources/*.osm ../../wahoo_mc/resources/*.py ./wahoo_mc/resources/
-cp -a ../../wahoo_mc/resources/json/ ./wahoo_mc/resources/json
-cp -a ../../wahoo_mc/resources/tag_wahoo_adjusted/ ./wahoo_mc/resources/tag_wahoo_adjusted
-cp -a ../../wahoo_mc/resources/tag_wahoo_initial/ ./wahoo_mc/resources/tag_wahoo_initial
+cp -a ../../wahoomc/*.py ./wahoomc/
+cp -a ../../wahoomc/resources/*.xml ./wahoomc/resources/
+cp -a ../../wahoomc/resources/*.osm ../../wahoomc/resources/*.py ./wahoomc/resources/
+cp -a ../../wahoomc/resources/json/ ./wahoomc/resources/json
+cp -a ../../wahoomc/resources/tag_wahoo_adjusted/ ./wahoomc/resources/tag_wahoo_adjusted
+cp -a ../../wahoomc/resources/tag_wahoo_initial/ ./wahoomc/resources/tag_wahoo_initial
 
 cp -a ../../docs/*.md ./docs/
 cp -a ../../CHANGELOG.md ../../README.md ./

docs/COPY_TO_WAHOO.md

@@ -2,7 +2,7 @@
 
 #### Table of contents <!-- omit in toc -->
 - [Steps to carry out](#steps-to-carry-out)
-  - [Unzip Files](#unzip-files)
+  - [Location of the generated maps](#location-of-the-generated-maps)
   - [Install adb](#install-adb)
   - [Authorize Wahoo device](#authorize-wahoo-device)
   - [Copy map files](#copy-map-files)
@@ -12,8 +12,10 @@
 - [Troubleshooting](#troubleshooting)
 
 # Steps to carry out
-## Unzip Files
-unzip the desired country files
+## Location of the generated maps
+The generated maps are saved in the user directory in folder: `$user_directory/wahooMapsCreatorData`.
+
+There is a folder per country or for the X/Y combination with the relevant tiles.
 
 ## Install adb
 You can download the lates adb-tools (included in the SDK Platform Tools) for your OS here:
@@ -38,7 +40,7 @@ adb devices
 ```
 
 ## Copy map files
-copy the unzipped map folders to \ELEMNT-BOLT\USB storage\maps\tiles\8\
+copy map folders per tile to \ELEMNT-BOLT\USB storage\maps\tiles\8\
 
 These tools can be helpful if you want to copy the files with a GUI and not via CLI:
 - Windows: https://github.com/hexadezi/adbGUI

docs/QUICKSTART_ANACONDA.md

@@ -8,8 +8,13 @@
     - [homebrew](#homebrew)
     - [OSM-tools](#osm-tools)
 - [wahooMapsCreator](#wahoomapscreator)
-- [Create Anaconda Environment](#create-anaconda-environment)
+  - [Create Anaconda Environment](#create-anaconda-environment)
+  - [Install wahooMapsCreator into Anaconda environment](#install-wahoomapscreator-into-anaconda-environment)
+    - [Update wahooMapsCreator](#update-wahoomapscreator)
 - [Run wahooMapsCreator](#run-wahoomapscreator)
+- [Archive](#archive)
+  - [old but still valid way to get wahooMapsCreator](#old-but-still-valid-way-to-get-wahoomapscreator)
+    - [Create Anaconda Environment](#create-anaconda-environment-1)
 
 # Download and Install required programs
 
@@ -54,11 +59,45 @@ brew install osmosis
 * more information: https://github.com/mapsforge/mapsforge/blob/master/docs/Getting-Started-Map-Writer.md#plugin-installation
 
 # wahooMapsCreator
-Download the latest .zip file from the [Releases](https://github.com/treee111/wahooMapsCreator/releases) page for your OS and save the folder on your drive. Extract the folder.
+## Create Anaconda Environment
+1. Open terminal (macOS/Linux) or **Anaconda Prompt** (Windows, via Startmenu)
+2. Create a new Anaconda environment with needed packages
+```
+conda create -n gdal-user python=3.7 geojson=2.5.* gdal=3.4.* pip --channel conda-forge
+```
+3. activate Anaconda environment with the command printed out (this needs to be done each time you want to use wahooMapsCreator maps)
+```
+conda activate gdal-user
+```
 
+## Install wahooMapsCreator into Anaconda environment
+```
+pip install wahoomc
+```
+
+### Update wahooMapsCreator
+If you have wahooMapsCreator already installed via pip and you want to install a newer version this can be done via:
+```
+pip install wahoomc --upgrade
+```
+
+If you want to upgrade to a version other than the release actual one, use this command:
+```
+pip install wahoomc==2.0.0a5 --upgrade 
+```
+
+# Run wahooMapsCreator
+Run wahooMapsCreater as described in the [README](../README.md/#Run-wahooMapsCreator)
+
+
+# Archive
+## old but still valid way to get wahooMapsCreator
+This was the way to install wahooMapsCreator until release v1.1.1
+
+Download the latest .zip file from the [Releases](https://github.com/treee111/wahooMapsCreator/releases) page for your OS and save the folder on your drive. Extract the folder.
 You can also clone the repository to have the latest coding.
 
-# Create Anaconda Environment
+### Create Anaconda Environment
 1. Open (or change to) the root of the extracted wahooMapsCreator folder in terminal (macOS/Linux) or **Anaconda Prompt** (Windows, via Startmenu)
 2. Create a new Anaconda environment via
 
@@ -77,5 +116,4 @@ conda activate gdal-user
 
 Additional informations: https://opensourceoptions.com/blog/how-to-install-gdal-with-anaconda/
 
-# Run wahooMapsCreator
-Run wahooMapsCreater as described in the [README](../README.md/#Run-wahooMapsCreator)
+continue with [Run wahooMapsCreator](#run-wahoomapscreator) to use wahooMapsCreator

docs/USAGE.md

@@ -5,14 +5,16 @@ wahooMapsCreator can be used in two different ways:
 
 Both ways support the same arguments to be used for the map-creation process. You can choose the arguments via GUI or as [CLI-arguments](#advanced-cli-usage).
 
+### Always activate environment first
+
 ## Run wahooMapsCreator for your country
 It might be a good idea to run wahooMapsCreator first for a small country e.g. Malta to check if everything is running fine.
 In a next step you can run it for your own country.
 
 ## GUI (Graphical User Interface)
 
 From the `root` folder of wahooMapsCreator, run:
-  - `python -m wahoo_mc gui`
+  - `python -m wahoomc gui`
 
 Set your arguments as required via the window:
 
@@ -21,34 +23,34 @@ Set your arguments as required via the window:
 ## CLI (Command Line Interface)
 
 From the `root` folder of wahooMapsCreator, run:
-- `python -m wahoo_mc cli -co <country_name>`
+- `python -m wahoomc cli -co <country_name>`
 
 Examples:
-- for Malta: `python -m wahoo_mc cli -co malta`
-- for Ireland: `python -m wahoo_mc cli -co ireland`
+- for Malta: `python -m wahoomc cli -co malta`
+- for Ireland: `python -m wahoomc cli -co ireland`
 
 ## Advanced CLI-Usage
 The script supports many arguments via command line.
 For a list of all supported arguments, run:
-- `python -m wahoo_mc cli -h`
+- `python -m wahoomc cli -h`
 
 ### Main arguments
 **Create maps for a country**
-- `python -m wahoo_mc cli -co <country>`
+- `python -m wahoomc cli -co <country>`
 
 **Create maps for X/Y coordinates**
 
 In particular for testing adjustments in configuration-files or coding it is helpful to create maps for only one tile or a handful of tiles!
 
 To create maps for only one tile and not a whole country, one can use the X/Y coordinates of that tile. X/Y coordinates can be retrieved from this in zoom-level 8: [link](http://tools.geofabrik.de/map/#8/50.3079/8.8026&type=Geofabrik_Standard&grid=1). 
-- `python -m wahoo_mc cli -xy <xy_coordinate,xy_coordinate>`
+- `python -m wahoomc cli -xy <xy_coordinate,xy_coordinate>`
 
 ### Examples
 - for Malta, download new maps if existing maps are older than 100 days and process files even if files exist
-  - `python -m wahoo_mc cli -co malta -md 100 -fp`
+  - `python -m wahoomc cli -co malta -md 100 -fp`
 - for Germany, download and process whole tiles which involves other countries than the given
-  - `python -m wahoo_mc cli -co germany -bc`
+  - `python -m wahoomc cli -co germany -bc`
 - to create maps for only one tile
-  - `python -m wahoo_mc cli -xy 134/88`
+  - `python -m wahoomc cli -xy 134/88`
 - for multiple tiles
-  - `python -m wahoo_mc cli -xy 134/88,133/88`
+  - `python -m wahoomc cli -xy 134/88,133/88`

pyproject.toml

@@ -0,0 +1,6 @@
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"

setup.cfg

@@ -0,0 +1,25 @@
+[metadata]
+name = wahoomc
+version = 2.0.0a5
+author = Benjamin Kreuscher
+author_email = [email protected]
+description = Create maps for your Wahoo bike computer based on latest OSM maps 
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/treee111/wahooMapsCreator
+project_urls =
+    Bug Tracker = https://github.com/treee111/wahooMapsCreator/issues
+classifiers =
+    Programming Language :: Python :: 3
+    License :: OSI Approved :: MIT License
+    Operating System :: OS Independent
+
+[options]
+packages = wahoomc
+python_requires = >=3.7
+install_requires =
+    requests==2.27.*
+    shapely==1.8.*
+
+[options.package_data]
+wahoomc = resources/*.*, resources/**/*.*, resources/*/*/*.*, resources/*/*/*/*.*