Merge pull request #261 from DavidJVitale/master

thanks @DavidJVitale @jyaistMap

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",
@@ -84,7 +84,7 @@
     "  * Select the release you want to install\n",
     "  * Click 'Install' and accept the terms and conditions\n",
     "\n",
-    "![install using ArcGIS Pro](../../static/img/guide_getstarted_InstallAndSetup_03.png)\n",
+    "![install using ArcGIS Pro](../../static/img/guide_getstarted_installandsetup_03.png)\n",
     "\n",
     "To use the API in different IDEs, proceed to **[Using the API](#Using-the-API)**\n",
     "\n",
@@ -98,7 +98,7 @@
     "    conda install -c esri arcgis\n",
     "    ```\n",
     "\n",
-    "![python command prompt](../../static/img/Python_Command_Prompt.png)\n",
+    "![python command prompt](../../static/img/python_command_prompt.png)\n",
     "\n",
     "To use the API in different IDEs, proceed to **[Using the API](#Using-the-API)**\n",
     "\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",
@@ -208,9 +224,9 @@
     "    \n",
     "You should see a map come up as shown below:\n",
     "\n",
-    "![test your install](../../static/img/guide_getstarted_InstallAndSetup_02.PNG)\n",
+    "![test your install](../../static/img/guide_getstarted_installandsetup_02.png)\n",
     "\n",
-    "Learn more about the API using the [guide](https://developers.arcgis.com/python/guide/) and try out the [samples](https://developers.arcgis.com/python/sample-notebooks/)."
+    "Learn more about the API using the [guide](../) and try out the [samples](../../sample-notebooks/)."
    ]
   },
   {
@@ -233,7 +249,7 @@
     " \n",
     "     `docker pull esridocker/arcgis-api-python-notebook`\n",
     "    \n",
-    "    ![docker pull command](../../static/img/guide_getstarted_InstallAndSetup_04.PNG)\n",
+    "    ![docker pull command](../../static/img/guide_getstarted_installandsetup_04.png)\n",
     "\n",
     "\n",
     " * Then spin the image into a container using the following command in terminal. Replace the `<localport>` with an available port number, for instance `8889`. \n",
@@ -243,7 +259,7 @@
     "\n",
     " * When the container starts, it will provide a URL (with a one time token) to open your local Notebook instance. Copy the URL and paste it in your browser's address bar to use the notebooks.\n",
     " \n",
-    "<h2><a name=\"Install-Offline\" style=\"color:black\"><strong>Install Offline</strong></a></h2>\n",
+    "## Install-Offline\n",
     "\n",
     "Install the API on a machine without internet access or on a disconnected network with the following steps:\n",
     "     \n",
@@ -261,13 +277,6 @@
     "<br>\n",
     "**NOTE:** For advanced users or those needing information on specific environments, see [Configuration](https://conda.io/docs/user-guide/configuration/use-condarc.html) for options to configure various aspects of conda"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
@@ -287,7 +296,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.5.5"
+   "version": "3.6.5"
   },
   "varInspector": {
    "cols": {

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

@@ -15,21 +15,37 @@
     "## 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",
     "* [numpy](http://www.numpy.org/)\n",
     "* [pyshp](https://pypi.python.org/pypi/pyshp/)\n",
     "* [matplotlib](https://matplotlib.org/)\n",
     "* [notebook](https://ipython.org/notebook.html)\n",
-    "* [ipywidgets >=5.2.2,<7](https://ipywidgets.readthedocs.io/en/stable/)\n",
-    "* [widgetsnbextension >=1.2.6,<3](https://pypi.python.org/pypi/widgetsnbextension)\n",
+    "* [ipywidgets >=7](https://ipywidgets.readthedocs.io/en/stable/)\n",
+    "* [widgetsnbextension >=3](https://pypi.python.org/pypi/widgetsnbextension)\n",
     "* [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.5.5"
+   "version": "3.6.5"
   }
  },
  "nbformat": 4,

guide/01-getting-started/understanding-conda.ipynb

@@ -111,13 +111,13 @@
     "\n",
     "`conda info --envs`\n",
     "\n",
-    "![conda_info_envs Image](../../static/img/guide_getstarted_UnderstandingConda01.png)\n",
+    "![conda_info_envs Image](../../static/img/guide_getstarted_understandingconda01.png)\n",
     "\n",
     "Enter the directory name and add python.exe to set the correct path to the Python interpreter for a specific environment. For example, the correct interpreter for the arcgispro-py3 environment in an IDE based on the screenshot above would be:\n",
     "\n",
     "`C:\\Program Files\\ArcGIS\\Pro\\bin\\Python\\envs\\arcgispro-py3\\python.exe`\n",
     "\n",
-    "![conda environment interpreter in PyCharm IDE](../../static/img/guide_getstarted_UnderstandingConda_pycharm.png)\n",
+    "![conda environment interpreter in PyCharm IDE](../../static/img/guide_getstarted_understandingconda_pycharm.png)\n",
     "\n",
     "See [Finding your Anaconda Python interpreter path](https://docs.anaconda.com/anaconda/user-guide/tasks/integration/python-path) for more detailed instructions on different systems.\n",
     "\n",
@@ -174,7 +174,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.4"
+   "version": "3.6.1"
   },
   "varInspector": {
    "cols": {

guide/01-getting-started/using-the-api.ipynb

@@ -39,9 +39,7 @@
   {
    "cell_type": "code",
    "execution_count": 2,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "gis = GIS(\"https://orgname.arcgis.com\", \"username\", \"password\")"
@@ -57,9 +55,7 @@
   {
    "cell_type": "code",
    "execution_count": 3,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "gis = GIS()"
@@ -75,9 +71,7 @@
   {
    "cell_type": "code",
    "execution_count": 4,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "gis?"
@@ -103,9 +97,7 @@
   {
    "cell_type": "code",
    "execution_count": 5,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "user = gis.users.get('rxsingh')"
@@ -121,9 +113,7 @@
   {
    "cell_type": "code",
    "execution_count": 6,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [
     {
      "data": {
@@ -171,9 +161,7 @@
   {
    "cell_type": "code",
    "execution_count": 7,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [
     {
      "data": {
@@ -200,9 +188,7 @@
   {
    "cell_type": "code",
    "execution_count": 8,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [
     {
      "data": {
@@ -236,9 +222,7 @@
   {
    "cell_type": "code",
    "execution_count": 9,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "map = gis.map(\"Palm Springs, CA\")\n",
@@ -263,7 +247,6 @@
    "cell_type": "code",
    "execution_count": 10,
    "metadata": {
-    "collapsed": false,
     "scrolled": false
    },
    "outputs": [
@@ -564,9 +547,7 @@
   {
    "cell_type": "code",
    "execution_count": 11,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "map.add_layer(items[8])"
@@ -589,9 +570,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.5.2"
+   "version": "3.6.1"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 1
 }

guide/01-getting-started/using-the-jupyter-notebook-environment.ipynb

@@ -26,7 +26,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "![Windows command prompt running jupyter notebook](../../static/img/guide_getstarted_UsingJupyterNotebooks_01.png)"
+    "![Windows command prompt running jupyter notebook](../../static/img/guide_getstarted_usingjupyternotebooks_01.png)"
    ]
   },
   {
@@ -44,7 +44,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "![Jupyter Notebook web application](../../static/img/guide_getstarted_UsingJupyterNotebooks_02.png)\n",
+    "![Jupyter Notebook web application](../../static/img/guide_getstarted_usingjupyternotebooks_02.png)\n",
     "\n",
     "The page you see in this image is called the Notebook Dashboard."
    ]
@@ -62,7 +62,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "![running a sample notebook](../../static/img/guide_GetStarted_UsingJupyterNotebooks_03.gif)\n",
+    "![running a sample notebook](../../static/img/guide_getstarted_usingjupyternotebooks_03.gif)\n",
     "\n",
     "When a cell is executing the cell number turns to an asterisk `(*)` and the circle next to the kernal name (Python 3 in the gif above) turns solid."
    ]
@@ -75,7 +75,7 @@
     "\n",
     "In addition to running the sample notebooks, you can create new notebooks for your projects. To do so, from the Notebook Dashboard page, click on the 'New' button and select a Python kernel of choice as shown in the image below.\n",
     "\n",
-    "![creating new notebooks](../../static/img/guide_getstarted_UsingJupyterNotebooks_04.png)\n",
+    "![creating new notebooks](../../static/img/guide_getstarted_usingjupyternotebooks_04.png)\n",
     "\n",
     "Alternately, you can create new notebooks from the 'File' menu of a running notebook. In the screenshot above, note the icons of currently running notebooks are green in color."
    ]
@@ -88,17 +88,10 @@
     "\n",
     "You can get a tour of the notebook interface from the `Help -> User Interface Tour` menu. As you get used to this new interface, you can enhance your productivity by learning a few keyboard shortcuts. Accessing `Help > Keyboard shortcuts` from a running notebook will bring up a help dialog as shown below.\n",
     "\n",
-    "![keyboard shortcuts](../../static/img/guide_getstarted_UsingJupyterNotebooks_05.png)\n",
+    "![keyboard shortcuts](../../static/img/guide_getstarted_usingjupyternotebooks_05.png)\n",
     "\n",
     "Among the shortcuts, `ctrl + shift + P` or `cmd + shift + P` on a mac is particularly useful as it brings up a command palette into which you can type what you wish to do and execute it. Refer to this blog article [Five tips to get you started with Jupyter notebooks](https://blogs.esri.com/esri/arcgis/2017/06/30/82220/) to get further understanding on patterns to follow while using Jupyter notebooks."
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
@@ -118,7 +111,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.4"
+   "version": "3.6.1"
   }
  },
  "nbformat": 4,