Repository: voxel51/fiftyone
Pull request: Reorganize installation docs
Closes #272
I think I cleaned up all of the cross-references between the two docs, but an extra set of eyes would be appreciated.

Problem statement:
Migrate virtualenv setup instructions to separate docs page
I like @lethosor's suggestion below. We can provide pip-only instructions first and then put virtualenv stuff on a separate page that users would refer to if they want help setting up their own dedicated environment:

> @lethosor Maybe we should move the virtual environment guide to to a separate page? It was originally intended for us to follow along with to get a standardized environment set up for demos, but I think it could confuse people who already have a usable environment set up by another tool (possibly related to Bill from Cloudfactory's PyCharm issue), and it takes up a large section of the page before the actual installation steps.

Hints from issue discussion:

Commit message: making link more obvious

Patch to review:
diff --git a/docs/source/getting_started/install.rst b/docs/source/getting_started/install.rst
index a11b6d0dd00..974cecf2919 100644
--- a/docs/source/getting_started/install.rst
+++ b/docs/source/getting_started/install.rst
@@ -3,14 +3,6 @@ FiftyOne Installation
 
 .. default-role:: code
 
-This page describes how to install FiftyOne in a
-`virtual environment <https://docs.python.org/3/tutorial/venv.html>`_.
-
-Using a virtual environment is strongly recommended because it allows
-maintaining an isolated environment in which FiftyOne and its dependencies can
-be installed. FiftyOne has many dependencies, some versions of which may
-conflict with versions already installed on your machine.
-
 Prerequisites
 -------------
 
@@ -22,119 +14,8 @@ platforms, Python can be downloaded
 suitable Python version is installed and accessible, run `python3 --version`
 or `python --version`.
 
-Creating a virtual environment
-------------------------------
-
-First, identify a suitable Python executable. On many systems, this will be
-`python3` , but it may be `python` on other systems instead. To confirm your
-Python version, pass `--version` to Python. Here is example output from running
-these commands:
-
-.. code-block:: text
-
-   $ python --version
-   Python 2.7.17
-   $ python3 --version
-   Python 3.6.9
-
-In this case, `python3` should be used in the next step.
-
-Navigate to a folder where you would like to create the virtual environment.
-Using the suitable Python version you have identified, run the following to
-create a virtual environment called `env` (you can choose any name):
-
-.. code-block:: shell
-
-   python3 -m venv env
-
-Replace `python3` at the beginning of a command if your Python executable has a
-different name. This will create a new virtual environment in the `env` folder,
-with standalone copies of Python and pip, as well as an isolated location to
-install packages to. However, this environment will not be used until it is
-*activated*. To activate the virtual environment, run the following command:
-
-.. tabs::
-
-  .. group-tab:: Linux/macOS
-
-    .. code-block:: shell
-
-      . env/bin/activate
-
-    Be sure to include the leading `.`
-
-  .. group-tab:: Windows
-
-    .. code-block:: text
-
-       env\Scripts\activate.bat
-
-After running this command, your shell prompt should begin with `(env)` , which
-indicates that the virtual environment has been activated. This state will only
-affect your current shell, so if you start a new shell, you will need to
-activate the virtual environment again to use it. When the virtual environment
-is active, `python` without any suffix will refer to the Python version you
-used to create the virtual environment, so you can use this for the remainder
-of this guide. For example:
-
-.. code-block:: text
-
-   $ python --version
-   Python 3.8.3
-
-Also note that `python` and `pip` live inside the `env` folder (in this output,
-the path to the current folder is replaced with `...`):
-
-.. tabs::
-
-  .. group-tab:: Linux/macOS
-
-    .. code-block:: text
-
-      $ which python
-      .../env/bin/python
-      $ which pip
-      .../env/bin/pip
-
-  .. group-tab:: Windows
-
-    .. code-block:: text
-
-      > where python
-      ...\env\Scripts\python.exe
-      C:\Program Files\Python38\python.exe
-      > where pip
-      ...\env\Scripts\pip.exe
-      C:\Program Files\Python38\Scripts\pip.exe
-
-Before you continue, you should upgrade `pip` and some related packages in the
-virtual environment. FiftyOne's packages rely on some newer pip features, so
-older pip versions may fail to locate a downloadable version of FiftyOne
-entirely. To upgrade, run the following command:
-
-.. code-block:: shell
-
-   pip install --upgrade pip setuptools wheel
-
-More virtual environment resources
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you ever want to leave an activated virtual environment and return to using
-your system-wide Python installation, run `deactivate`.
-
-There are lots of ways to set up and work with virtual environments, some of
-which are listed here. These may be particularly useful to review if you are
-dealing with virtual environments frequently:
-
-* The `venv` module used in this guide is documented
-  `here <https://docs.python.org/3/library/venv.html>`_, with information on
-  additional arguments that the `venv` command accepts.
-* There is a similar
-  `virtualenv package <https://pypi.org/project/virtualenv/>`_
-  (`pip install virtualenv`) that supports older Python versions.
-* `virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/>`_
-  adds some convenient shell support for creating and managing virtual
-  environments.
+We encourage installing FiftyOne in a virtual environment. See
+:doc:`setting up a virtual environment <virtualenv>` for more details.
 
 .. _installing-fiftyone:
 
@@ -147,15 +28,15 @@ Installing FiftyOne
   welcome email contains a token that you will need to run some of the commands
   below. Replace all instances of ``YOUR_TOKEN`` below with your token.
 
-  If you haven't registered for the FiftyOne Beta, you can sign up at
-  https://voxel51.com/fiftyone/#beta
+  If you haven't registered for the FiftyOne Beta,
+  `you can sign up here! <https://share.hsforms.com/1KuTDtQYWRTyU0yHNGgBFfw2ykyk>`_
 
-To install FiftyOne in a virtual environment, ensure that the virtual
-environment is active as described in the previous section, and then run the
-command below:
+To install FiftyOne in a virtual environment, ensure you have activated any
+virtual environment that you are using, then run:
 
 .. code-block:: shell
 
+   pip install --upgrade pip setuptools wheel
    pip install --index https://YOUR_TOKEN@pypi.voxel51.com fiftyone
 
 This will install FiftyOne and all of its dependencies, which may take some
@@ -170,11 +51,11 @@ your virtual environment:
    Type "help", "copyright", "credits" or "license" for more information.
    >>>
    >>> import fiftyone as fo
-   >>> fo.__file__
-   '.../env/lib/python3.X/site-packages/fiftyone/__init__.py'
    >>>
-   >>> session = fo.launch_app()
-   >>> exit()
+
+A successful installation of FiftyOne should result in no output when
+`fiftyone` is imported. See below for help with troubleshooting error
+messages that you may encounter.
 
 **Mac users:**
 
@@ -191,8 +72,8 @@ your virtual environment:
 - The ``psutil`` package may require Python headers to be installed on your
   system. On Debian-based distributions, these are available in the
   ``python3-dev`` package.
-- If you encounter an error related to MongoDB failing to start, such as "Could
-  not find mongod", you may need to install additional packages. See the
+- If you encounter an error related to MongoDB failing to start, such as `Could
+  not find mongod`, you may need to install additional packages. See the
   `troubleshooting section <#troubleshooting>`_ for details.
 
 **Windows users:**
diff --git a/docs/source/getting_started/virtualenv.rst b/docs/source/getting_started/virtualenv.rst
new file mode 100644
index 00000000000..fe4479dd6bf
--- /dev/null
+++ b/docs/source/getting_started/virtualenv.rst
@@ -0,0 +1,136 @@
+
+.. _virtualenv-guide:
+
+Virtual Environment Setup
+=========================
+
+.. default-role:: code
+
+.. toctree::
+   :hidden:
+
+This page describes how to install FiftyOne in a
+`virtual environment <https://docs.python.org/3/tutorial/venv.html>`_.
+
+Using a virtual environment is strongly recommended because it allows
+maintaining an isolated environment in which FiftyOne and its dependencies can
+be installed. FiftyOne has many dependencies, some versions of which may
+conflict with versions already installed on your machine.
+
+Creating a virtual environment using `venv`
+-------------------------------------------
+
+First, identify a suitable Python executable. On many systems, this will be
+`python3` , but it may be `python` on other systems instead. To confirm your
+Python version, pass `--version` to Python. Here is example output from running
+these commands:
+
+.. code-block:: text
+
+   $ python --version
+   Python 2.7.17
+   $ python3 --version
+   Python 3.6.9
+
+In this case, `python3` should be used in the next step.
+
+Navigate to a folder where you would like to create the virtual environment.
+Using the suitable Python version you have identified, run the following to
+create a virtual environment called `env` (you can choose any name):
+
+.. code-block:: shell
+
+   python3 -m venv env
+
+Replace `python3` at the beginning of a command if your Python executable has a
+different name. This will create a new virtual environment in the `env` folder,
+with standalone copies of Python and pip, as well as an isolated location to
+install packages to. However, this environment will not be used until it is
+*activated*. To activate the virtual environment, run the following command:
+
+.. tabs::
+
+  .. group-tab:: Linux/macOS
+
+    .. code-block:: shell
+
+      . env/bin/activate
+
+    Be sure to include the leading `.`
+
+  .. group-tab:: Windows
+
+    .. code-block:: text
+
+       env\Scripts\activate.bat
+
+After running this command, your shell prompt should begin with `(env)` , which
+indicates that the virtual environment has been activated. This state will only
+affect your current shell, so if you start a new shell, you will need to
+activate the virtual environment again to use it. When the virtual environment
+is active, `python` without any suffix will refer to the Python version you
+used to create the virtual environment, so you can use this for the remainder
+of this guide. For example:
+
+.. code-block:: text
+
+   $ python --version
+   Python 3.8.3
+
+Also note that `python` and `pip` live inside the `env` folder (in this output,
+the path to the current folder is replaced with `...`):
+
+.. tabs::
+
+  .. group-tab:: Linux/macOS
+
+    .. code-block:: text
+
+      $ which python
+      .../env/bin/python
+      $ which pip
+      .../env/bin/pip
+
+  .. group-tab:: Windows
+
+    .. code-block:: text
+
+      > where python
+      ...\env\Scripts\python.exe
+      C:\Program Files\Python38\python.exe
+      > where pip
+      ...\env\Scripts\pip.exe
+      C:\Program Files\Python38\Scripts\pip.exe
+
+Before you continue, you should upgrade `pip` and some related packages in the
+virtual environment. FiftyOne's packages rely on some newer pip features, so
+older pip versions may fail to locate a downloadable version of FiftyOne
+entirely. To upgrade, run the following command:
+
+.. code-block:: shell
+
+   pip install --upgrade pip setuptools wheel
+
+To leave an activated virtual environment and return to using your system-wide
+Python installation, run `deactivate`. For more documentation on `venv`,
+including additional setup options,
+`see here <https://docs.python.org/3/library/venv.html>`_.
+
+Alternatives to `venv`
+----------------------
+
+There are lots of ways to set up and work with virtual environments, some of
+which are listed here. These may be particularly useful to review if you are
+dealing with virtual environments frequently:
+
+* There is a similar
+  `virtualenv package <https://pypi.org/project/virtualenv/>`_
+  (`pip install virtualenv`) that supports older Python versions.
+* `virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/>`_
+  adds some convenient shell support for creating and managing virtual
+  environments.
+
+.. warning::
+
+  We currently discourage using `pipenv` with FiftyOne, as it has known issues
+  with installing packages from custom package indices.


Code review comments:
diff_hunk: @@ -0,0 +1,136 @@
+
+.. _virtualenv-guide:
+
+Virtual Environment Setup
+=========================
+
+.. default-role:: code
+
+.. toctree::
path: docs/source/getting_started/virtualenv.rst
text: @user1:
I think we're at the point now where not every page needs to be visible in the ToC. I removed this one so that `Installation` is a single element entry

@author:
It's only visible on the installation page, like how the tutorials are only visible from the tutorials page (and sub-pages). I think having it linked to from one extra place makes it a bit easier to find from the installation page, and it won't clutter up the sidebar on any other pages.

More generally, Sphinx expects every page to be reachable through at least one TOC (although it doesn't have to be the root-level TOC). As-is, we will get a warning about this every time we build the docs. I think we should pay attention to that warning and put the page in a TOC.