Revamp installation page

docs/conf.py

@@ -25,6 +25,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.doctest",
     "sphinx.ext.extlinks",
+    "sphinx_tabs.tabs",
     "sphinxcontrib.programoutput",
     "sphinxcontrib.httpdomain",
     "rasabaster.button",
@@ -87,7 +88,6 @@
     "Thumbs.db",
     ".DS_Store",
     # ignore doc pages that we don't show to appease keep_warnings
-    "multi-skill-assistants.rst",
     "core/old-core-change-log.rst",
     "core/old-core-migration-guide.rst",
     "nlu/old-nlu-change-log.rst",

docs/user-guide/installation.rst

@@ -9,42 +9,183 @@ Installation
 
 .. edit-link::
 
-The recommended way to get started with Rasa is via ``pip``:
+Quick Installation
+~~~~~~~~~~~~~~~~~~
 
-.. copyable::
+You can install both Rasa and Rasa X using pip with the following command (requires Python >= 3.5.4).
 
-    pip install rasa-x --extra-index-url https://pypi.rasa.com/simple
+.. code-block:: bash
+
+    $ pip install rasa-x --extra-index-url https://pypi.rasa.com/simple
 
-This will install both Rasa and Rasa X.
-If you don't want to use Rasa X, run ``pip install rasa`` instead.
+Once you're done with this, you can head over to the tutorial!
 
-.. raw:: html
+.. button::
+   :text: Next Step: Tutorial
+   :link: ../rasa-tutorial/
 
-     Unless you've already got numpy & scipy installed, we highly recommend
-     that you install and use
-     <a class="reference external" href="https://www.anaconda.com/download/"
-     target="_blank">Anaconda</a>.
+|
+-------------------------------------------
 
-If you want to use the development version of Rasa, you can get it from GitHub:
+For a more detailed guide on setting up Rasa with pip, follow along the :ref:`installation guide <installation_guide>`. You can also :ref:`build Rasa from source <build_from_source>`.
+
+If you have a specific pipeline in mind and want to install dependencies for that,
+head over to the section on :ref:`pipeline dependencies <pipeline_dependencies>`.
+
+
+.. _installation_guide:
+
+Installation Guide with pip
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Install the Python development environment
+---------------------------------------------
+
+Check if your Python environment is already configured:
 
 .. code-block:: bash
 
-    git clone https://github.com/RasaHQ/rasa.git
-    cd rasa
-    pip install -r requirements.txt
-    pip install -e .
+    $ python3 --version
+    $ pip3 --version
+    $ virtualenv --version
+
+If these packages are already installed, these commands should display version
+numbers for each step, and you can skip to the next step.
+
+Otherwise, proceed with the instructions below to install them.
+
+.. tabs::
+
+    .. tab:: Ubuntu
+
+        Fetch the relevant packages using ``apt``, and install virtualenv using ``pip``.
+
+        .. code-block:: bash
+
+            $ sudo apt update
+            $ sudo apt install python3-dev python3-pip
+            $ sudo pip3 install -U virtualenv
+
+    .. tab:: macOS
+
+        Install the `Homebrew <https://brew.sh>`_ package manager if you haven't already.
+
+        Once you're done, you can install Python and virtualenv.
+
+        .. code-block:: bash
+
+            $ brew update
+            $ brew install python  # Python 3
+            $ sudo pip3 install -U virtualenv  # system-wide install
+
+    .. tab:: Windows
+
+        .. raw:: html
+
+            Make sure the Microsoft VC++ Compiler is installed, so python can compile
+            any dependencies. You can get the compiler from <a class="reference external"
+            href="https://visualstudio.microsoft.com/visual-cpp-build-tools/"
+            target="_blank">Visual Studio</a>. Download the installer and select
+            VC++ Build tools in the list.
+
+        Install `Python 3 <https://www.python.org/downloads/windows/>`_ (64-bit version) for Windows.
+
+        .. code-block:: bat
+
+            C:\> pip3 install -U pip virtualenv
+
+
+2. Create a virtual environment (strongly recommended)
+------------------------------------------------------
+
+Tools like `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ and `virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/>`_ provide isolated Python environments, which are cleaner than installing packages systemwide. They also let you install packages without root privileges.
+
+.. tabs::
+
+    .. tab:: Ubuntu / macOS
+
+        Create a new virtual environment by choosing a Python interpreter and making a ``./venv`` directory to hold it:
+
+        .. code-block:: bash
+
+            $ virtualenv --system-site-packages -p python3 ./venv
+
+        Activate the virtual environment:
+
+        .. code-block:: bash
+
+            $ source ./venv/bin/activate
 
-Windows Prerequisites
-~~~~~~~~~~~~~~~~~~~~~
+    .. tab:: Windows
 
-.. raw:: html
+        Create a new virtual environment by choosing a Python interpreter and making a ``.\venv`` directory to hold it:
 
-     Make sure the Microsoft VC++ Compiler is installed, so python can compile
-     any dependencies. You can get the compiler from <a class="reference external"
-     href="https://visualstudio.microsoft.com/visual-cpp-build-tools/"
-     target="_blank">Visual Studio</a>. Download the installer and select
-     VC++ Build tools in the list.
+        .. code-block:: bat
 
+            C:\> virtualenv --system-site-packages -p python3 ./venv
+
+        Activate the virtual environment:
+
+        .. code-block:: bat
+
+            C:\> .\venv\Scripts\activate
+
+
+3. Install Rasa and Rasa X
+--------------------------
+
+.. tabs::
+
+    .. tab:: Inside a virtualenv
+
+        To install both Rasa and Rasa X in one go:
+
+        .. code-block:: bash
+
+            (venv) $ pip install rasa-x --extra-index-url https://pypi.rasa.com/simple
+
+        If you just want to install Rasa without Rasa X:
+
+        .. code-block:: bash
+
+            (venv) $ pip install rasa
+
+    .. tab:: System-wide install
+
+        To install both Rasa and Rasa X in one go:
+
+        .. code-block:: bash
+
+            $ pip3 install --user rasa-x --extra-index-url https://pypi.rasa.com/simple
+
+        If you just want to install Rasa without Rasa X:
+
+        .. code-block:: bash
+
+            $ pip3 install --user rasa
+
+.. admonition:: Congratulations! You have successfully installed Rasa!
+
+    You can now head over to the :ref:`tutorial <rasa-tutorial>`.
+
+|
+-------------------------------------------
+
+.. _build_from_source:
+
+Building from Source
+~~~~~~~~~~~~~~~~~~~~
+
+If you want to use the development version of Rasa, you can get it from GitHub:
+
+.. code-block:: bash
+
+    $ git clone https://github.com/RasaHQ/rasa.git
+    $ cd rasa
+    $ pip install -r requirements.txt
+    $ pip install -e .
+
+.. _pipeline_dependencies:
 
 NLU Pipeline Dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -61,12 +202,11 @@ will help you pick which pipeline to use.
     If you want to make sure you have the dependencies
     installed for any component you might ever need, and you
     don't mind the additional dependencies lying around, you can use
+    this to install everything:
 
     .. code-block:: bash
 
-        pip install -r alt_requirements/requirements_full.txt
-
-    to install everything.
+        $ pip install -r alt_requirements/requirements_full.txt
 
 
 Great for getting started: pretrained embeddings from spaCy
@@ -81,9 +221,9 @@ You can install it with the following commands:
 
 .. code-block:: bash
 
-    pip install rasa[spacy]
-    python -m spacy download en_core_web_md
-    python -m spacy link en_core_web_md en
+    $ pip install rasa[spacy]
+    $ python -m spacy download en_core_web_md
+    $ python -m spacy link en_core_web_md en
 
 This will install Rasa NLU as well as spacy and its language model
 for the English language. We recommend using at least the
@@ -92,17 +232,16 @@ default small ``en_core_web_sm`` model. Small models require less
 memory to run, but will somewhat reduce intent classification performance.
 
 
-
-First Alternative: Tensorflow
+First Alternative: TensorFlow
 -----------------------------
 
-To use the ``supervised_embeddings`` pipeline you will need to install
-Tensorflow and, for entity recognition, the sklearn-crfsuite library.
-To do this, simply run the following command:
+The ``supervised_embeddings`` pipeline uses TensorFlow and the sklearn-crfsuite
+library as dependencies. However, these are installed automatically along
+with a standard Rasa installation that you get from doing:
 
 .. code-block:: bash
-
-    pip install rasa
+    
+    $ pip install rasa
 
 
 .. _install-mitie:
@@ -118,8 +257,8 @@ First, run
 
 .. code-block:: bash
 
-    pip install git+https://github.com/mit-nlp/MITIE.git
-    pip install rasa[mitie]
+    $ pip install git+https://github.com/mit-nlp/MITIE.git
+    $ pip install rasa[mitie]
 
 and then download the
 `MITIE models <https://github.com/mit-nlp/MITIE/releases/download/v0.4/MITIE-models-v0.2.tar.bz2>`_.
@@ -128,21 +267,9 @@ anywhere. If you want to use MITIE, you need to
 tell it where to find this file (in this example it was saved in the
 ``data`` folder of the project directory).
 
-The complete pipeline for MITIE can be found here
-
-.. literalinclude:: ../../sample_configs/config_pretrained_embeddings_mitie.yml
-    :language: yaml
-
-Using MITIE alone can be quite slow to train, but you can use it with this configuration.
-
-
-.. literalinclude:: ../../sample_configs/config_pretrained_embeddings_mitie_2.yml
-    :language: yaml
-
-
 
 Next Step
----------
+~~~~~~~~~
 
 Now that you have everything installed, head over to the tutorial!
 

requirements-docs.txt

@@ -6,6 +6,7 @@ pygments==2.2.0
 sphinxcontrib-httpdomain==1.6.1
 sphinxcontrib-websupport==1.1.0
 sphinxcontrib-trio==1.0.2
+sphinx-tabs==1.1.11
 sphinx-autodoc-typehints==1.6.0
 https://storage.googleapis.com/docs-theme/rasabaster-0.7.23.tar.gz
 git+https://github.com/RasaHQ/sphinxcontrib-versioning.git#egg=sphinxcontrib-versioning