Add release instructions and update installation steps [skip ci]

docs/devguide.txt

@@ -25,6 +25,7 @@ If you intent is to contribute to the development BigARTM, please proceed to the
    devguide/ipython_windows.txt
    devguide/dev_build_linux.txt
    devguide/code_style.txt
+   devguide/release.txt
 
 Wiki pages:
 

docs/devguide/release.txt

@@ -0,0 +1,57 @@
+Release new version
+===================
+
+This is a memo for BigARTM maintaineres about releasing new BigARTM version.
+
+* Submit and integrate pull request against ``master`` branch to
+
+  * bump version in ``src/artm/CMakeLists.txt``,
+  * bump version in ``python/setup.py``,
+  * update links to the latest release in ``docs/downloads.txt``.
+
+* Run installation tests in `bigartm-install <https://github.com/bigartm/bigartm-install>`_ repository
+
+  * Bump version in `install.sh <https://github.com/bigartm/bigartm-install/edit/master/install.sh>`_ script
+  * Submit pull request and inspect both personal builds - for Appveyor (Windows) and for Travis (Linux)
+  * If installation build fails investigate and fix issues before releasing the new version
+
+* Submit and integrate pull request against `stable` branch to integrate all changes from `master` branch.
+
+  .. warning::
+
+     Choose REBASE option when merging pull request. DO NOT use squash commits option.
+
+  .. warning::
+
+     Make sure to wait for personal build (appveyor and travis), and investigate issues if builds are failing.
+
+* Create new release `here <https://github.com/bigartm/bigartm/releases>`_:
+
+  * fill in ``vX.Y.Z`` tag
+  * fill in a description, using previous release as an example
+  * download ``BigARTM.7z`` from ``python2`` job in the latest appveyor build.
+    Rename it to ``BigARTM_vX.Y.Z_win64.7z``, and attach as binary to the release.
+
+* Update `bigartm-docker <https://github.com/bigartm/bigartm-docker>`_ repo and image
+
+  * Only once: install docker from https://www.docker.com/ .
+    If you run docker in a VM, configure memory to at least 8 GB (otherwise docker build fails to compile bigartm c++ code).
+    If you are new to docker, read `a tutorial <https://docs.docker.com/engine/getstarted/step_six/>`_ on how to publish containers on docker hub.
+  * Edit `Dockerfile <https://github.com/bigartm/bigartm-docker/edit/master/Dockerfile>`_ to update BigARTM version in the `git clone` command.
+    Click ``Commit changes`` to submit this change directly to master branch of ``bigartm-docker`` repository.
+  * Clone ``bigartm/bigartm-docker`` repository and open command shell. Change working directory to the root of ``bigartm-docker`` repository.
+  * Build and publish the image. Example:
+
+    .. code-block:: bash
+
+       docker build .
+       docker login
+       docker images   # to find the tag
+       docker tag e744db1be133 ofrei/bigartm:v0.8.2
+       docker tag e744db1be133 ofrei/bigartm:latest
+       docker push ofrei/bigartm:v0.8.2
+       docker push ofrei/bigartm:latest
+
+   * Try to execute commands from `bigartm-docker/README.md <https://github.com/bigartm/bigartm-docker/blob/master/README.md>`_ to test the image.
+
+* Send an announce e-mail to ``bigartm-users@googlegroups.com``

docs/download.txt

@@ -4,7 +4,7 @@ Downloads
 * **Windows**
 
   * Latest 64 bit release: `BigARTM_v0.8.2_win64 <https://github.com/bigartm/bigartm/releases/download/v0.8.2/BigARTM_v0.8.2_win64.7z>`_
-  * Latest build from master branch: `BigARTM_master_win64.7z <https://ci.appveyor.com/api/projects/bigartm/bigartm/artifacts/BigARTM.7z?branch=master&job=Environment%3A%20JOB%3Dpython3%2C%20PYTHON_VERSION%3D3.5%2C%20MINICONDA%3DC%3A%5CMiniconda35-x64>`_ (warning, use this with caution)
+  * Latest build from master branch: `BigARTM_master_win64.7z <https://ci.appveyor.com/api/projects/bigartm/bigartm/artifacts/BigARTM.7z?branch=stable&job=Environment%3A%20PYTHON_VERSION%3D3.5%2C%20MINICONDA%3DC%3A%5CMiniconda35-x64>`_ (warning, use this with caution)
   * All previous releases are available at https://github.com/bigartm/bigartm/releases
 
   Please refer to :doc:`tutorials/windows_basic` for step by step installation procedure.
@@ -15,6 +15,10 @@ Downloads
   (https://github.com/bigartm/bigartm) and build it as described in 
   :doc:`tutorials/linux_basic`.
 
+* **Docker container**
+
+  On any OS it is possible to run BigARTM as docker container, as described in :doc:`installation/docker`
+
 * **Datasets**
 
   Download one of the following datasets to start experimenting with BigARTM.

docs/installation/docker.txt

@@ -0,0 +1,36 @@
+Installation as Docker container
+================================
+
+On any OS it is possible to run BigARTM as docker container.
+
+1. Get the image from DockerHub
+
+  .. code-block:: bash
+
+     docker pull ofrei/bigartm
+
+2. Run CLI
+
+  .. code-block:: bash
+
+     docker run -t -i ofrei/bigartm bigartm
+
+3. Try Python API (use ``ipython2`` or ``ipython3`` depending on which python version you prefer)
+
+  .. code-block:: bash
+
+     $ docker run -t -i ofrei/bigartm ipython2
+     Python 2.7.6 (default, Jun 22 2015, 17:58:13) 
+     Type "copyright", "credits" or "license" for more information.
+
+     IPython 3.2.1 -- An enhanced Interactive Python.
+     ?         -> Introduction and overview of IPython's features.
+     %quickref -> Quick reference.
+     help      -> Python's own help system.
+     object?   -> Details about 'object', use 'object??' for extra details.
+
+     In [1]: import artm
+
+     In [2]: model = artm.ARTM()
+
+See `bigartm-docker <https://github.com/bigartm/bigartm-docker>`_ repo for more information.

docs/installation/index.txt

@@ -10,6 +10,7 @@ Installation
 
    windows
    linux
+   docker
 
 
 .. vim:ft=rst

docs/installation/linux.txt

@@ -4,6 +4,60 @@ Installation for Linux and Mac OS-X users
 Currently there is no distribution package of BigARTM for Linux.
 BigARTM had been tested on several Linux distributions, and it is known to work well,
 but you have to get the source code and compile it locally on your machine.
+You may also try BigARTM from pre-built docker container, as described in :doc:`docker`.
+
+Script to install BigARTM
+-------------------------
+
+The following script is tested with Ubuntu 14.04.
+
+.. code-block:: bash
+
+    # Step 1. Update and install dependencies
+    apt-get --yes update
+    apt-get --yes install git
+    apt-get --yes install make
+    apt-get --yes install cmake
+    apt-get --yes install build-essential
+    apt-get --yes install libboost-all-dev
+
+    # Step 2. Insall python packages
+    apt-get --yes install python-numpy
+    apt-get --yes install python-pandas
+    wget https://bootstrap.pypa.io/get-pip.py
+    python get-pip.py
+    pip install protobuf
+    pip install tqdm
+
+    # Step 3. Clone repository and build
+    git clone --branch=stable https://github.com/bigartm/bigartm.git
+    cd bigartm
+    mkdir build && cd build
+    cmake ..
+    make
+
+    # Step 4. Install BigARTM
+    make install
+    export ARTM_SHARED_LIBRARY=/usr/local/lib/libartm.so
+
+Now you should be able to use BigARTM command line utility (try ``bigartm --help``),
+or run BigARTM from python, like this: ``import artm; print(artm.version()); print(artm.ARTM(num_topics=10).info)``.
+
+**On rpm-based distributions** replace first step of the script with
+
+.. code-block:: bash
+
+   sudo yum install git make cmake gcc-c++ glibc-static libstdc++-static boost boost-static python
+   
+
+For Fedora 22 or higher use ``dnf`` instead of ``yum``.
+
+**On Mac OS distributions** replace first step with ``brew install git cmake boost``.
+At step 4 replace ``libartm.so`` with ``libartm.dylib``.
+
+If the instructions above did not work for you please let us know
+(either create an `issue <https://github.com/bigartm/bigartm/issues/new>`_
+or send e-mail to `bigartm-users@googlegroups.com <https://groups.google.com/group/bigartm-users>`_).
 
 System dependencies
 -------------------
@@ -15,27 +69,18 @@ Building BigARTM requires the following components:
       *g++* or *clang* compiler with c++11 support,
       `boost <boost.org>`_ (at least of version 1.40) --
       for building library and binary executable;
-    * `python <https://python.org>`_ (version 2.7) --
+    * `python <https://python.org>`_ (version 2.7 or 3.4) --
       for building Python API for BigARTM.
 
-To simplify things, you may type:
-
-* **On deb-based distributions**:
-  ``sudo apt-get install git make cmake build-essential libboost-all-dev``
-
-* **On rpm-based distributions**:
-  ``sudo yum install git make cmake gcc-c++ glibc-static libstdc++-static boost boost-static python``
-  (for Fedora 22 or higher use ``dnf`` instead of ``yum``) 
-
-* **On Mac OS distributions**:
-  ``brew install git cmake boost``
 
+Building C++ code with CMake
+----------------------------
 
-Download sources and build
---------------------------
+BigARTM is hosted at github repository, with two branches --- ``stable`` and ``master``.
+``stable`` contains latest stable release, while ``master`` is the latest version of the code.
+Normally ``master`` is also quite stable, so do not hesitate to try this branch.
 
-Clone the latest BigARTM code from our github repository,
-and build it via CMake as in the following script.
+Build is built  via CMake, as in the following script.
 
 .. code-block:: bash
 
@@ -78,11 +123,13 @@ By default ``CMAKE_INSTALL_PREFIX=/usr/local/``.
 Configure BigARTM Python API
 ----------------------------
 
-If you want to use only Python interface for BigARTM, you may run following commands:
+Python's interface of BigARTM is normally configured by running ``make install``.
+As an alternative you may configure it manually as described below, however you still need to build native code of BigARTM with ``make``.
 
 .. code-block:: bash
 
    # Step 1 - install Google Protobuf as dependency
+   # (this can be replaced by "pip install protobuf")
    cd ~/bigartm/3rdparty/protobuf/python
    sudo python setup.py install
 
@@ -94,7 +141,7 @@ If you want to use only Python interface for BigARTM, you may run following comm
    export ARTM_SHARED_LIBRARY=~/bigartm/build/lib/libartm.so        # for linux
    export ARTM_SHARED_LIBRARY=~/bigartm/build/lib/libartm.dylib     # for Mac OS X
 
-We strongly recommend system-wide installation as
+We strongly recommend system-wide installation (e.g. ``make install``) as
 there is no need to keep BigARTM code after it, so you may safely
 remove folder ``~/bigartm/``.
 

docs/installation/windows.txt

@@ -5,65 +5,56 @@ Download
 --------
 
 Download latest binary distribution of BigARTM from https://github.com/bigartm/bigartm/releases.
-Explicit download links can be found at :doc:`/download` section (for 32 bit and 64 bit configurations).
+Explicit download links can be found at :doc:`/download` section (64 bit only).
 
 The distribution will contain pre-build binaries, command-line interface and BigARTM API for Python.
 The distribution also contains a simple dataset.
 More datasets in BigARTM-compatible format are available in the :doc:`/download` section.
 
-Refer to :doc:`/ref/windows_distribution` for details about other files, included in the binary distribution package.
+You may also try BigARTM from pre-built docker container, as described in :doc:`docker`.
 
-Configure BigARTM Python API
-----------------------------
+Use BigARTM from command line
+-----------------------------
 
-1.  Install Python, for example from the following links:
+Download the latest package from https://github.com/bigartm/bigartm/releases.
+Unpack it to ``C:\BigARTM``.
+Open command line or power shell and change working directory to ``C:\BigARTM\bin``.
+Now you may use BigARTM command line utility ``bigartm.exe``.
+Go to :doc:`/tutorials/bigartm_cli` for examples and further directions.
 
-    * Python 2.7.11, 64 bit --  https://www.python.org/ftp/python/2.7.11/python-2.7.11.amd64.msi, or
-    * Python 2.7.11, 32 bit -- https://www.python.org/ftp/python/2.7.11/python-2.7.11.msi
+Configure BigARTM Python API
+----------------------------
 
-    Remember that the version of BigARTM package must match your version Python installed on your machine.
-    If you have 32 bit operating system then you must select 32 bit for Python and BigARTM package.
-    If you have 64 bit operating system then you are free to select either version.
-    However, please note that memory usage of 32 bit processes is limited by 2 GB.
-    For this reason we recommend to select 64 bit configurations.
+1.  Install Python, for example from Anaconda distribution (https://www.continuum.io/downloads).
+    You are free to choose ``Python 2.7`` or ``Python 3``, both are supported with BigARTM.
+    You have to choose 64 bit Python installation.
 
-    Please note that you must use ``Python 2.7``, because ``Python 3`` is not
-    supported by BigARTM.
-
-    Also you need to have several Python libraries to be installed on your machine:
-
-    * numpy >= 1.9.2
-    * pandas >= 0.16.2
+2.  Install Python packages that BigARTM depend on.
 
+    * ``numpy >= 1.9.2`` (skip this if you install via Anaconda)
+    * ``pandas >= 0.16.2`` (skip this if you install via Anaconda)
+    * ``protobuf >= 3.0.0`` (not included in Anaconda; install by running ``pip install protobuf==3.0.0``)
+    * ``tqdm`` (not included in Anaconda; install by running ``pip install tqdm``)
 
-2.  Add ``C:\BigARTM\bin`` folder to your ``PATH`` system variable, and
+3.  Add ``C:\BigARTM\bin`` folder to your ``PATH`` system variable, and
     add ``C:\BigARTM\python`` to your ``PYTHONPATH`` system variable:
 
     .. code-block:: bash
   
        set PATH=%PATH%;C:\BigARTM\bin
-       set PATH=%PATH%;C:\Python27;C:\Python27\Scripts
        set PYTHONPATH=%PYTHONPATH%;C:\BigARTM\Python
 
-    Remember to change ``C:\BigARTM`` and ``C:\Python27`` with your local folders.
-
-3.  Setup *Google Protocol Buffers* library, included in the BigARTM release package.
-
-    * Copy ``C:\BigARTM\bin\protoc.exe`` file into ``C:\BigARTM\protobuf\src`` folder
-    * Run the following commands from command prompt
-
-    .. code-block:: bash
-  
-        cd C:\BigARTM\protobuf\Python
-        python setup.py build
-        python setup.py install
+    Remember to change ``C:\BigARTM`` if you unpack to another location.
 
-    Avoid ``python setup.py test`` step, as it produces several confusing errors. Those errors are harmless.
-    For further details about protobuf installation refer to `protobuf/python/README
-    <https://raw.githubusercontent.com/bigartm/bigartm/master/3rdparty/protobuf/python/README.txt>`_.
+4. Now you can used BigARTM from Python shell or from ipython notebook.
+   Refer to :doc:`/tutorials/python_api` for examples,
+   or to :doc:`/python_interface` for documentation.
 
-.. If you are getting errors when configuring or using Python API,
-   please refer to Troubleshooting chapter in :doc:`/installation/linux`.
-   The list of issues is common between Windows and Linux.
+If you are getting errors when configuring or using Python API,
+please refer to Troubleshooting chapter in :doc:`/installation/linux`.
+The list of issues is common between Windows and Linux.
+Normally you should install protobuf for python with ``pip install``.
+An alternative way is to install it from the package that comes with BigARTM.
+This is described `here <https://github.com/bigartm/bigartm/wiki/Q&A#how-to-install-python-protobuf-from-bigartm-package-on-windows>`_.
 
 .. vim:ft=rst