From 12e44a46f2ee6a8ce9c68b51e9c4e10408116943 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferdinand=20M=C3=BCtsch?= Date: Wed, 10 Feb 2021 21:26:41 +0100 Subject: [PATCH] docs: update readme and docs chore: increment version --- README.md | 53 +++++++++++++++++++++++++++++++--------- docs/index.md | 6 +++-- docs/installation.md | 58 ++++++++++++++++++++++++++++++++------------ mkdocs.yml | 2 +- setup.py | 8 +++--- 5 files changed, 92 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index d42e64c..3c93912 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,15 @@ # 🌍 pyquadkey2 [![Documentation](https://docs.muetsch.io/badge.svg)](https://docs.muetsch.io/pyquadkey2/) -This is a feature-rich Python implementation of [QuadKeys](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system), an approach to **geographical tiling**, that was proposed by Microsoft to be used for Bing Maps. +![](https://docs.microsoft.com/en-us/bingmaps/articles/media/5cff54de-5133-4369-8680-52d2723eb756.jpg) + +This is a feature-rich Python implementation of [QuadKeys](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system), an approach to **geographical tiling**, popularized by Microsoft to be used for Bing Maps. In essence, the concept is to **recursively** divide the flat, two-dimensional world map into squares. Each square contains **four squares** as children, which again contain four squares and so on, up **centimeter-level precision**. Each of these squares is **uniquely identifiable with a string** like `021030032`. For more details on the concept, please refer to the [original article](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system). -[n1try/pyquadkey2](https://github.com/n1try/pyquadkey2) originates from a **fork** of [buckhx/QuadKey](https://github.com/buckhx/QuadKey), which is not maintained anymore. It build on top of that project and adds: +[muety/pyquadkey2](https://github.com/muety/pyquadkey2) originates from a **fork** of [buckhx/QuadKey](https://github.com/buckhx/QuadKey), which is not maintained anymore. It build on top of that project and adds: * βœ… Several (critical) [bug fixes](https://github.com/buckhx/QuadKey/pull/15) * βœ… Python 3 support @@ -19,25 +21,52 @@ For more details on the concept, please refer to the [original article](https:// ## Installation ### Requirements -This library requires **Python 3.6** or higher. To compile it by yourself, Cython is required in addition. +This library requires **Python 3.6** or higher. To compile it from source, Cython is required in addition. ### Using Pip -* `pip3 install pyquadkey2` +```bash +$ pip install pyquadkey2 +``` Pip installation is only tested for Linux and Mac, yet. If you encounter problems with the installation on Windows, please report them as a new issue. ### From archive -* Download the latest [release](https://github.com/n1try/pyquadkey2/releases) as archive (`.tar.gz`) or wheel (`.whl`), e.g. `0.1.1.tar.gz` -* Install it with pip: `pip3 install 0.1.1.tar.gz` +```bash +$ wget https://github.com/muety/pyquadkey2/releases/download/0.2.1/pyquadkey2-0.2.1.tar.gz +$ pip install pyquadkey2-0.2.1.tar.gz +``` ### From source -* Clone repository: `git clone https://github.com/n1try/pyquadkey2` -* Make sure Cython is installed: `pip3 install cython` -* Compile Cython modules: `cd pyquadkey2/quadkey/tilesystem && python3 setup.py build_ext --inplace && ../../` -* Install the library with Pip: `pip3 install .` +#### Prerequisites (`Linux`) +* `gcc` + * Fedora: `dnf install @development-tools` + * Ubuntu / Debian: `apt install build-essential` +* `python3-devel` + * Fedora: `dnf install python3-devel` + * Ubuntu / Debian: `apt install python3-dev` + * Others: See [here](https://stackoverflow.com/questions/21530577/fatal-error-python-h-no-such-file-or-directory/21530768#21530768) + +#### Prerequisites (`Windows`) +* Visual C++ Build Tools 2015 (with Windows 10 SDK) (see [here](https://devblogs.microsoft.com/python/unable-to-find-vcvarsall-bat/#i-need-a-package-that-has-no-wheel-what-can-i-do)) + +#### Build +```bash +# Check out repo +$ git clone https://github.com/muety/pyquadkey2 + +# Create and active virtual environment (optional) +$ python -m venv ./venv +$ source venv/bin/activate + +# Install depencencies +$ pip install -r requirements.txt + +# Compile +$ cd src/pyquadkey2/quadkey/tilesystem && python setup.py build_ext --inplace && cd ../../../.. -### Troubleshooting -* `ImportError: cannot import name 'tilesystem'`: Simply try `pip3 install --upgrade pyquadkey2` once again. Second time usually works, as required build extensions are installed then. This is a known issue and will be fixed in the future. +# Install as module +$ pip install . +``` ## License Apache 2.0 diff --git a/docs/index.md b/docs/index.md index 1f65056..9181e2b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,11 +1,13 @@ # 🌍 Introduction -This is a feature-rich Python implementation of [QuadKeys](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system), an approach to **geographical tiling**, that was proposed by Microsoft to be used for Bing Maps. +This is a feature-rich Python implementation of [QuadKeys](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system), an approach to **geographical tiling**, popularized by Microsoft to be used for Bing Maps. + +![](https://docs.microsoft.com/en-us/bingmaps/articles/media/5cff54de-5133-4369-8680-52d2723eb756.jpg) In essence, the concept is to **recursively** divide the flat, two-dimensional world map into squares. Each square contains **four squares** as children, which again contain four squares and so on, up **centimeter-level precision**. Each of these squares is **uniquely identifiable with a string** like `021030032`. For more details on the concept, please refer to the [original article](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system). -[n1try/pyquadkey2](https://github.com/n1try/pyquadkey2) originates from a **fork** of [buckhx/QuadKey](https://github.com/buckhx/QuadKey), which is not maintained anymore. It build on top of that project and adds: +[muety/pyquadkey2](https://github.com/muety/pyquadkey2) originates from a **fork** of [buckhx/QuadKey](https://github.com/buckhx/QuadKey), which is not maintained anymore. It build on top of that project and adds: * βœ… Several (critical) [bug fixes](https://github.com/buckhx/QuadKey/pull/15) * βœ… Python 3 support diff --git a/docs/installation.md b/docs/installation.md index 1d9b7e6..3b61d08 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,22 +1,48 @@ -# Installation +## Installation +### Requirements +This library requires **Python 3.6** or higher. To compile it from source, Cython is required in addition. -## Requirements -This library requires **Python 3.6** or higher. To compile it by yourself, Cython is required in addition. - -## Using Pip -* `pip3 install pyquadkey2` +### Using Pip +```bash +$ pip install pyquadkey2 +``` Pip installation is only tested for Linux and Mac, yet. If you encounter problems with the installation on Windows, please report them as a new issue. -## From archive -* Download the latest [release](https://github.com/n1try/pyquadkey2/releases) as archive (`.tar.gz`) or wheel (`.whl`), e.g. `0.1.1.tar.gz` -* Install it with pip: `pip3 install 0.1.1.tar.gz` +### From archive +```bash +$ wget https://github.com/muety/pyquadkey2/releases/download/0.2.1/pyquadkey2-0.2.1.tar.gz +$ pip install pyquadkey2-0.2.1.tar.gz +``` + +### From source +#### Prerequisites (`Linux`) +* `gcc` + * Fedora: `dnf install @development-tools` + * Ubuntu / Debian: `apt install build-essential` +* `python3-devel` + * Fedora: `dnf install python3-devel` + * Ubuntu / Debian: `apt install python3-dev` + * Others: See [here](https://stackoverflow.com/questions/21530577/fatal-error-python-h-no-such-file-or-directory/21530768#21530768) + +#### Prerequisites (`Windows`) +* Visual C++ Build Tools 2015 (with Windows 10 SDK) (see [here](https://devblogs.microsoft.com/python/unable-to-find-vcvarsall-bat/#i-need-a-package-that-has-no-wheel-what-can-i-do)) + +#### Build +```bash +# Check out repo +$ git clone https://github.com/muety/pyquadkey2 + +# Create and active virtual environment (optional) +$ python -m venv ./venv +$ source venv/bin/activate + +# Install depencencies +$ pip install -r requirements.txt -## From source -* Clone repository: `git clone https://github.com/n1try/pyquadkey2` -* Make sure Cython is installed: `pip3 install cython` -* Compile Cython modules: `cd pyquadkey2/quadkey/tilesystem && python3 setup.py build_ext --inplace && ../../` -* Install the library with Pip: `pip3 install .` +# Compile +$ cd src/pyquadkey2/quadkey/tilesystem && python setup.py build_ext --inplace && cd ../../../.. -## Troubleshooting -* `ImportError: cannot import name 'tilesystem'`: Simply try `pip3 install --upgrade pyquadkey2` once again. Second time usually works, as required build extensions are installed then. This is a known issue and will be fixed in the future. +# Install as module +$ pip install . +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 853819d..a5bd706 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,5 +5,5 @@ nav: - Documentation: - 'Instantiation': 'instantiation.md' - 'Methods': 'methods.md' - - GitHub: 'https://github.com/n1try/pyquadkey2' + - GitHub: 'https://github.com/muety/pyquadkey2' theme: 'readthedocs' \ No newline at end of file diff --git a/setup.py b/setup.py index 8f66109..bba96f2 100644 --- a/setup.py +++ b/setup.py @@ -12,13 +12,13 @@ setup( name='pyquadkey2', - version='0.2.0', + version='0.2.1', description='Python implementation of geographical tiling using QuadKeys as proposed by Microsoft', long_description=long_description, long_description_content_type='text/markdown', author='Ferdinand MΓΌtsch', author_email='ferdinand@muetsch.io', - url='https://github.com/n1try/pyquadkey2', + url='https://github.com/muety/pyquadkey2', packages=find_packages('src'), package_dir={'': 'src'}, classifiers=[ @@ -34,8 +34,8 @@ 'Typing :: Typed' ], project_urls={ - 'Bug Tracker': 'https://github.com/n1try/pyquadkey2/issues', - 'Source Code': 'https://github.com/n1try/pyquadkey2', + 'Bug Tracker': 'https://github.com/muety/pyquadkey2/issues', + 'Source Code': 'https://github.com/muety/pyquadkey2', 'Documentation': 'https://docs.muetsch.io/pyquadkey2/' }, keywords='tiling quadkey quadtile geospatial geohash',