Merge pull request #246 from DavidJVitale/dev_site_current

thanks @DavidJVitale

Author: AtmaMani

guide/01-getting-started/install-and-set-up.ipynb

@@ -20,7 +20,7 @@
     "  - [Install Using ArcGIS Pro Python Package Manager](#Install-using-ArcGIS-Pro-Python-Package-Manager)\n",
     "  - [Install Using the Python Command Prompt](#Install-using-Python-Command-Prompt)\n",
     "  - [Install Using Anaconda for Python Distribution](#Install-using-Anaconda-for-Python-Distribution)\n",
-    "  - [Install Using pip](#Install-using-pip)\n",
+    "  - [Install Using pip or pipenv](#Install-using-pipenv-or-pip)\n",
     "    - [Install without Dependencies](#Install-without-Dependencies)\n",
     " - [Upgrade the `arcgis` package](#Upgrade-the-arcgis-package)\n",
     "   - [ArcGIS Pro 2.1](#ArcGIS-Pro-2.1)\n",
@@ -118,17 +118,33 @@
     "\n",
     "To use the API in different IDEs, proceed to **[Using the API](#Using-the-API)**\n",
     "\n",
-    "### Install using pip\n",
+    "### Install using pipenv or pip\n",
     "\n",
-    "[Pip](https://pip.pypa.io/en/stable/) is a package management system used to install and manage software packages written in Python, similar to conda. Many pip packages can be found in the [Python Package Index (PyPI)](https://pypi.python.org/pypi), including the ArcGIS API for Python pip package. To install the API with pip, open a terminal and enter the following command:\n",
+    "#### Pipenv\n",
+    "[Pipenv](https://docs.pipenv.org/) is the official packaging tool for managing environments and installing packages from the [Python Package Index (PyPI)](https://pypi.python.org/pypi). To install the ArcGIS API for Python from PyPI in a new environment, create a new folder named `your-folder`. Open a terminal, and run `cd /path/to/your-folder` to change directories into `your-folder`. Then, enter the following command to simultaneously create a new environment and install the API in it:\n",
+    "\n",
+    "```\n",
+    "pipenv install arcgis\n",
+    "```\n",
+    "\n",
+    "After running this command, you will notice that a new file named `Pipfile` was created in `your-folder`. A [Pipfile](https://github.com/pypa/pipfile) contains package information that represents a python environment. Open your terminal and make sure you are still in the `your-folder` directory; then, run `pipenv shell`. You have now activated your python environment, the environment that contains the `arcgis` package! You can run `jupyter notebook` or `python` in this environment to start using the API.\n",
     "    \n",
-    "```python\n",
+    "Pipenv differs from conda and other environment managers in that environments are specific to the folder that contains the Pipfile. In this way, pipenv's use of `Pipfile` is similar to how `npm` uses `package.json`. To learn more about installing and using pipenv, click [here](https://docs.pipenv.org/) or [here](http://docs.python-guide.org/en/latest/dev/virtualenvs/#installing-packages-for-your-project).\n",
+    "\n",
+    "> __Tip__: You can run any command in an environment without activating it by running `pipenv run {insert_command_here}` in a directory with a valid Pipfile.\n",
+    "\n",
+    "#### Pip\n",
+    "\n",
+    "[Pip](https://pip.pypa.io/en/stable/) is the predecessor of pipenv, and can also be used to install packages from PyPI (but you must manage environments with seperate tools like [virtualenv](https://virtualenv.pypa.io/en/stable/)). To install the API with pip, open a terminal and enter the following command:\n",
+    "    \n",
+    "```\n",
     "pip install arcgis\n",
     "```\n",
     "\n",
-    "Pip and conda are totally seperate package managers, and should avoid being used interchangeably. It is recommended you use conda to install the API if you are a beginner user. [Read more about the differences](https://stackoverflow.com/questions/20994716/what-is-the-difference-between-pip-and-conda).\n",
+    "#### Disclaimer\n",
+    "You should avoid mixing conda with pipenv/pip: they are completely seperate package managers. It is recommended that you use conda to install the API if you are a beginner user. Read more about the differences [here](https://stackoverflow.com/questions/20994716/what-is-the-difference-between-pip-and-conda) and [here](http://docs.python-guide.org/en/latest/dev/virtualenvs/).\n",
     "\n",
-    "> Note: when installing the ArcGIS API for Python with pip, some dependencies may require Microsoft Visual C++ 14.0. If you see any errors related to this, either install the Microsoft Visual C++ tools or install the API without dependencies.\n",
+    "> __Note__: when installing the ArcGIS API for Python with pipenv/pip, some dependencies may require Microsoft Visual C++ 14.0. If you see any errors related to this, either install the Microsoft Visual C++ tools or install the API without dependencies.\n",
     "\n",
     "### Install without Dependencies\n",
     "\n",
@@ -280,7 +296,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.1"
+   "version": "3.6.5"
   },
   "varInspector": {
    "cols": {

guide/01-getting-started/system-requirements.ipynb

@@ -15,7 +15,7 @@
     "## Dependencies\n",
     "The full power of the ArcGIS API for Python is best experienced when all its dependencies are installed. However, specific tasks such as GIS administration and content management can be accomplished with just the [`six`](https://pypi.python.org/pypi/six) package installed. See [Install without Dependencies](../install-and-set-up/#Install-without-Dependencies) to install the `arcgis` package in this manner.\n",
     "\n",
-    "It is recommended to install the `arcgis` package the default way of either `conda install -c esri arcgis` or `pip install arcgis`. When installed in this manner, all the below dependencies are automatically installed. (Note that most of these packages have dependencies of their own.)\n",
+    "It is recommended to install the `arcgis` package the default way of either `conda install -c esri arcgis` or `pipenv install arcgis`. When installed in this manner, all the below dependencies are automatically installed. Note that most of these packages have dependencies of their own.\n",
     "\n",
     "* [six](https://pypi.python.org/pypi/six)\n",
     "* [pandas](https://pandas.pydata.org/)\n",
@@ -28,8 +28,24 @@
     "* [keyring](https://pypi.python.org/pypi/keyring/10.6.0)\n",
     "* [winkerberos](https://pypi.python.org/pypi/winkerberos/0.7.0) (Windows only)\n",
     "\n",
-    "> Note: if `arcpy` is found in the current python environment, it may be used in various locations. Otherwise, `pyshp` will be used. See [SpatialDataFrame](https://esri.github.io/arcgis-python-api/apidoc/html/arcgis.features.toc.html?highlight=spatialdataframe#spatialdataframe) for more information."
+    "> Note: if `arcpy` is found in the current python environment, it may be used in various locations. Otherwise, `pyshp` will be used. See [SpatialDataFrame](https://esri.github.io/arcgis-python-api/apidoc/html/arcgis.features.toc.html?highlight=spatialdataframe#spatialdataframe) for more information.\n",
+    "\n",
+    "### Optional Dependencies\n",
+    "\n",
+    "There are some other python packages that may be required to use certain functionality in the API, but are __not__ automatically installed. To use that functionality, you must manually call `conda install {package_name}` or `pipenv install {package_name}` for the below packages:\n",
+    "\n",
+    "* [beautifulsoup](https://www.crummy.com/software/BeautifulSoup/) - used when authenticating with OAuth2.\n",
+    "* [dill](https://pypi.org/project/dill/#description) - used when creating a Python toolbox from a method."
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -48,7 +64,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.1"
+   "version": "3.6.5"
   }
  },
  "nbformat": 4,