diff --git a/docs/_static/images/pycharm/pycharm-interpreter-existing-meatball-menu.png b/docs/_static/images/pycharm/pycharm-interpreter-existing-meatball-menu.png new file mode 100644 index 0000000000..b0fa9eb604 Binary files /dev/null and b/docs/_static/images/pycharm/pycharm-interpreter-existing-meatball-menu.png differ diff --git a/docs/_static/images/pycharm/pycharm-mark-directory-as-sources-root.png b/docs/_static/images/pycharm/pycharm-mark-directory-as-sources-root.png new file mode 100644 index 0000000000..e11205ec96 Binary files /dev/null and b/docs/_static/images/pycharm/pycharm-mark-directory-as-sources-root.png differ diff --git a/docs/_static/images/pycharm/pycharm-select-interpreter.png b/docs/_static/images/pycharm/pycharm-select-interpreter.png new file mode 100644 index 0000000000..50d0f5f370 Binary files /dev/null and b/docs/_static/images/pycharm/pycharm-select-interpreter.png differ diff --git a/docs/_static/images/pycharm/pycharm-settings-add-interpreter.png b/docs/_static/images/pycharm/pycharm-settings-add-interpreter.png new file mode 100644 index 0000000000..f9a0cfe8f1 Binary files /dev/null and b/docs/_static/images/pycharm/pycharm-settings-add-interpreter.png differ diff --git a/docs/_static/images/pycharm/pycharm-settings-menu-location-windows.png b/docs/_static/images/pycharm/pycharm-settings-menu-location-windows.png new file mode 100644 index 0000000000..e13c00d39a Binary files /dev/null and b/docs/_static/images/pycharm/pycharm-settings-menu-location-windows.png differ diff --git a/docs/_static/images/pycharm/pycharm-settings-project-interpreter-location.png b/docs/_static/images/pycharm/pycharm-settings-project-interpreter-location.png new file mode 100644 index 0000000000..7aa075d8a2 Binary files /dev/null and b/docs/_static/images/pycharm/pycharm-settings-project-interpreter-location.png differ diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 77d0723bb4..0215a8009a 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -21,3 +21,4 @@ stand alone. See errors on iOS internal/index publishing/index + tooling-settings-pycharm diff --git a/docs/how-to/tooling-settings-pycharm.rst b/docs/how-to/tooling-settings-pycharm.rst new file mode 100644 index 0000000000..c827a698d7 --- /dev/null +++ b/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: 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.