[docs] adjust pybindings build docs to new build system

1 files changed, 48 insertions, 93 deletions

diff --git a/docs/building_pybindings.txt b/docs/building_pybindings.txt
index 43c974cb67..171ab81f91 100644
--- a/docs/building_pybindings.txt
+++ b/docs/building_pybindings.txt
@@ -7,121 +7,76 @@ be using python 3.
 This document describes how to build these python bindings.
 
 
-Installing Boost.Python
------------------------
-
+Preparing source tree
+---------------------
 The MAPS.ME project comes with its own version of Boost (https://www.boost.org/)
-in a submodule. While most of the project uses boost in the header-only mode,
-you will need to build the Boost.Python library to link against if you need
-python bindings.
+in a submodule. You have to recursively update submodules before you start
+building anything.
 
-Once you've run
+Ensure you have ran:
 
   $ git submodule update --init --recursive
 
-and
-
-  $ ./configure.sh
-
-from omim's root directory, you'll have the Boost headers installed but the
-python library will not be built by default, so we'll need to build it
-manually. (The less clean alternative is to
-link against the version of library installed in your system in case you have
-a system installation of Boost. This is not recommended.)
-
-The official instruction for Boost 1.68 is here: https://www.boost.org/doc/libs/1_68_0/libs/python/doc/html/building/configuring_boost_build.html.
-
-Here is a recap.
-
-Write the paths to your python binary, headers and libraries in a .jam-file.
-We will edit the auto-generated file omim/3party/boost/project-config.jam
-which omim's configure.sh should have generated by now.
-Unfortunately, Boost's bootstrap.sh (called from omim's configures.sh) that generates
-this file is not sufficiently versatile to allow us provide the necessary paths
-at the ./configure.sh stage.
-
-We will append the python config to the end of project-config.jam.
-Boost.Build does not work well with duplicating "using python" rules for the same
-version so if you've made a mistake, manually edit the file instead of appending
-a version with corrected paths.
-
-Example for a macOS installation:
-
-    $ pwd
-
-    /omim/3party/boost
-
-    $ cat >>project-config.jam <<EOF
-
-using python
-  : 3.7
-  : /usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/bin/python3
-  : /usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/Headers
-  : /usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/lib
-  ;
-EOF
-
-    $ ./b2 --with-python python=3.7 --build-dir=build-python37 cxxflags="-fPIC"
-
-(On some systems "-fPIC" is not needed)
-
-The syntax is
-    using python : <version> : <python binary> : <path to python headers> : <path to python libraries> ;
 
-Newlines are allowed, semicolon is required.
-If there are several versions of Boost.Python that you want to build,
-they can all be added to the same .jam-file with this "using python" directive.
 
-If you want to remove the python libraries, you'll have to do it by manually removing
-the build directory. (b2 provides a "--clean" flag which seems to be broken)
+Building single pybinding module
+--------------------------------
+Find a correspoding module's setup.py.
+Current list of available modules and setup's:
 
-   $ pwd
+- generator/mwm_diff/pymwm_diff/setup.py
+- generator/pygen/setup.py
+- kml/pykmlib/setup.py
+- local_ads/pylocal_ads/setup.py
+- search/pysearch/setup.py
+- tracking/pytracking/setup.py
+- traffic/pytraffic/setup.py
 
-    /omim/3party/boost
+Run chosen setup.py with Python you want to build binding for.
+Examples:
 
-   $ rm -r build-python37
+  $ python kml/pykmlib/setup.py build install
+  $ python3.6 generator/mwm_diff/pymwm_diff/setup.py bdist_wheel 
 
+During build, our setup.py will configure and build boost_python library for
+needed Python version, configure omim, and build needed binding.
 
 
-Building pybindings
--------------------
+Building all pybindings modules
+-------------------------------
+Run generic pyhelpers/setup.py with needed Python. This will invoke build (or
+other actions) for all pybindings.
 
-Now you're ready to build omim's CMake targets that link against Boost.Python.
 
-Do not forget to clean CMake's caches (by purging the build/ directory, for example)
-if something goes wrong during the CMake stage.
+Supported actions and options
+-----------------------------
+Please refer to setuptools/distutils documentation for description of all
+available commands.
+Main commands are:
+ build
+ install
+ bdist_wheel
 
-    $ pwd
+Notable option for build command:
 
-    /omim
+  --omim-builddir [path to omim builddir]
 
-    $ mkdir ../build-omim
-    $ cd ../build-omim
-    $ cmake ../omim \
-       -DPYBINDINGS=ON \
-       -DPYBINDINGS_VERSION=9.5.0 \
-       -DPYTHON_VERSION=3.7.5
+It should be used to store build dir somewhere outside source tree. If not
+specified, everything will be build in directory `build` from current
+directory.
 
-    (make sure that the version match what you've provided in the .jam file
-     when building the Boost.Python lib)
+Complete wheels generation example:
+  $ python3.7 pyhelpers/setup.py build --omim-builddir ../omim-build/ bdist_wheel
 
-    $ make -j4 pysearch
+This will create wheels for all pybindings in `../omim-build/pybindings-dist/`.
 
-If the above invocation of CMake fails to find the correct
-python installation on your system, you may need to help it:
 
-     $ cmake ../omim \
-         -DPYBINDINGS=ON \
-         -DPYBINDINGS_VERSION=9.5.0 \
-         -DPYTHON_VERSION=3.7.5 \
-         -DPYTHON_EXECUTABLE=/usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/bin/python3 \
-         -DPYTHON_INCLUDE_DIR=/usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/Headers \
-         -DPYTHON_LIBRARY=/usr/local/opt/python3/Frameworks/Python.framework/Versions/3.7/lib/libpython3.7m.dylib
+Pip installation
+----------------
 
+One can install pybinding straight from source:
 
-Test your newly built target:
+  $ pip install git+https://github.com/mapsme/omim.git@master#egg=pykmlib&subdirectory=kml/pykmlib
 
-    $ MWM_RESOURCES_DIR=../omim/data \
-      MWM_WRITABLE_DIR=..omim/data \
-      PYTHONPATH=. \
-      ../omim/search/pysearch/run_search_engine.py
+But this can be a long wait, it is better to use already compiled .whl
+distribution.