Adds guide for configuring PyCharm while using briefcase.

docs/how-to/index.rst

@@ -21,3 +21,4 @@ stand alone.
  See errors on iOS <see_errors_on_ios>
  internal/index
  publishing/index
+ tooling-settings-pycharm

docs/how-to/tooling-settings-pycharm.rst

@@ -0,0 +1,116 @@
+Setting Up PyCharm to work with Briefcase
+============================================
+
+Using PyCharm with briefcase is a relatively straightforward endeavor, but
+requires knowledge of how PyCharm determines where your code lives. For those
+familiar with PyCharm's directory marking tools, the steps are as follows:
+
+1. Set your project interpreter to the same environment where you have
+ briefcase installed.
+2. Mark the application `src` directory as a sources root.
+
+If you do not know how to do either of these, keep reading:
+
+Set Your Project Interpreter
+-------------------------------------
+
+The `briefcase dev -r` command updates the requirements of the current
+application as user-space installs in the same python environment that it's
+installed in. Because of this, you need to set your project interpreter to the
+same environment.
+
+.. note::
+ If you created your project in PyCharm and installed briefcase into the
+ virtual environment it created for you, you do not need to complete this
+ step.
+
+If you are unsure of where briefcase is installed, in the default `app.py` that
+is generated by briefcase add the following anywhere in the file after the
+imports.
+
+.. code::
+
+ print(sys.executable)
+
+This is the same way briefcase identifies the current environment executable
+and you should have a line in your output that is a file path to a python
+executable. Once you have this, you can delete the line from your code.
+
+Next, you need to open your interpreter settings:
+
+.. tabs::
+
+ .. group-tab:: MacOS
+
+ First open the settings by navigating to the PyCharm menu and selecting
+ Settings. Alternatively, use CMD and , to open the settings window.
+
+
+ .. group-tab:: Windows
+
+ First open the settings by navigating to the File menu and selecting
+ Settings. Alternatively use CTR ALT S to
+ open the settings window.
+
+ .. image:: /_static/images/pycharm/pycharm-settings-menu-location-windows.png
+ :alt: A screenshot of the File menu in Pycharm with the Settings option
+ highlighted. It's located just under "Rename Project..." and
+ "Remote Development..."
+
+Then navigate to Project: <project name> in the left hand pane, and then
+Python Interpreter.
+
+.. image:: /_static/images/pycharm/pycharm-settings-project-interpreter-location.png
+ :alt: A screenshot of the IDE settings window with highlights on the
+ "Project Settings" underneath "Version Control" option in the left hand
+ pane. In the main portion of the window, a link for Python Interpreter
+ is highlighted.
+
+Once you're in the interpreter settings, click the "Add interpreter" button
+next to the Python Interpreter drop down.
+
+.. image:: /_static/images/pycharm/pycharm-interpreter-existing-meatball-menu.png
+ :alt: A screen shot of the add interpreter screen. The radio button next to
+ Environment is set to Existing as opposed to new and a yellow highlight
+ is calling attention to a button to the right hand side that is marked
+ with three dots.
+
+This opens up a file selector. If you paste the file path of the interpreter
+you got back at the start of this section, that should select the correct
+executable in the menu. Click the Okay button (primary action button) on this
+screen and the one you return to and your interpreter settings should be set!
+
+.. image:: /_static/images/pycharm/pycharm-select-interpreter.png
+ :alt: A file selection box. At the top is a box highlighted that accepts a
+ file path. You can paste the executable location here or navigate via
+ the folder structure below to select the appropriate interpreter.
+
+Remember that `briefcase` will be managing your dependency installs, so you
+will need to run `briefcase dev -r` each time you add a dependency and then
+wait for PyCharm to index the new library before auto-complete will work.
+
+This solves auto-completion of installed libraries in PyCharm, the following
+step will allow the packages that are part of your application to be indexed
+and supported.
+
+Set Your Sources Root
+--------------------------------------
+
+In general, PyCharm automatically assumes that your sources root and project
+directory are the same. When keeping your code in a sub-directory (like
+`project/src` in a briefcase project) you need to mark the `src` directory as
+your sources root in order for auto-complete to find your local code.
+
+To do so, in the Project explorer pane, highlight the `src` folder and right
+click. Near the very bottom of the context menu, there is an option called
+"Mark Directory as..." Inside the mark directory sub-menu, select Sources Root,
+which should have a blue folder icon.
+
+.. image:: /_static/images/pycharm/pycharm-mark-directory-as-sources-root.png
+ :alt: A screenshot of the context menu when right clicking on a directory
+ in the project pane. Near the bottom is a blue highlighted menu item
+ "Mark Directory as..." and a sub-menu to the right with the
+ "Sources Root" option at the top of the list.
+
+In your project pane, your `src` directory should now be blue. Now PyCharm's
+auto-complete will make suggestions from the packages directly.