New tutorial: Using PyCharm with Pyramid

13 files changed, 357 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
index bc711f8ff..93b550d60 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -108,6 +108,7 @@ platforms.
    tutorials/wiki/index.rst
    tutorials/bfg/index.rst
    tutorials/modwsgi/index.rst
+   tutorials/pycharm/index.rst
 
 API Documentation
 ==================
diff --git a/docs/tutorials/pycharm/images/create_new_project.png b/docs/tutorials/pycharm/images/create_new_project.png
new file mode 100644
index 000000000..f15068b65
--- /dev/null
+++ b/docs/tutorials/pycharm/images/create_new_project.png
diff --git a/docs/tutorials/pycharm/images/create_setup.png b/docs/tutorials/pycharm/images/create_setup.png
new file mode 100644
index 000000000..de4cb364b
--- /dev/null
+++ b/docs/tutorials/pycharm/images/create_setup.png
diff --git a/docs/tutorials/pycharm/images/create_virtual_environment.png b/docs/tutorials/pycharm/images/create_virtual_environment.png
new file mode 100644
index 000000000..0bd3c9263
--- /dev/null
+++ b/docs/tutorials/pycharm/images/create_virtual_environment.png
diff --git a/docs/tutorials/pycharm/images/edit_run_debug_configurations.png b/docs/tutorials/pycharm/images/edit_run_debug_configurations.png
new file mode 100644
index 000000000..7708fa9dc
--- /dev/null
+++ b/docs/tutorials/pycharm/images/edit_run_debug_configurations.png
diff --git a/docs/tutorials/pycharm/images/install_package.png b/docs/tutorials/pycharm/images/install_package.png
new file mode 100644
index 000000000..944a05f6a
--- /dev/null
+++ b/docs/tutorials/pycharm/images/install_package.png
diff --git a/docs/tutorials/pycharm/images/install_package_pyramid.png b/docs/tutorials/pycharm/images/install_package_pyramid.png
new file mode 100644
index 000000000..05a209b6c
--- /dev/null
+++ b/docs/tutorials/pycharm/images/install_package_pyramid.png
diff --git a/docs/tutorials/pycharm/images/install_package_setuptools.png b/docs/tutorials/pycharm/images/install_package_setuptools.png
new file mode 100644
index 000000000..8932a3f40
--- /dev/null
+++ b/docs/tutorials/pycharm/images/install_package_setuptools.png
diff --git a/docs/tutorials/pycharm/images/python_interpreters_1.png b/docs/tutorials/pycharm/images/python_interpreters_1.png
new file mode 100644
index 000000000..6b1455001
--- /dev/null
+++ b/docs/tutorials/pycharm/images/python_interpreters_1.png
diff --git a/docs/tutorials/pycharm/images/python_interpreters_2.png b/docs/tutorials/pycharm/images/python_interpreters_2.png
new file mode 100644
index 000000000..61c3de2b1
--- /dev/null
+++ b/docs/tutorials/pycharm/images/python_interpreters_2.png
diff --git a/docs/tutorials/pycharm/images/run_configuration.png b/docs/tutorials/pycharm/images/run_configuration.png
new file mode 100644
index 000000000..4612b2b3c
--- /dev/null
+++ b/docs/tutorials/pycharm/images/run_configuration.png
diff --git a/docs/tutorials/pycharm/images/start_up_screen.png b/docs/tutorials/pycharm/images/start_up_screen.png
new file mode 100644
index 000000000..c65e01eeb
--- /dev/null
+++ b/docs/tutorials/pycharm/images/start_up_screen.png
diff --git a/docs/tutorials/pycharm/index.rst b/docs/tutorials/pycharm/index.rst
new file mode 100644
index 000000000..1b7c07f98
--- /dev/null
+++ b/docs/tutorials/pycharm/index.rst
@@ -0,0 +1,356 @@
+**************************
+Using PyCharm with Pyramid
+**************************
+
+This tutorial is a very brief overview of how to use PyCharm with Pyramid.
+`PyCharm <http://www.jetbrains.com/pycharm/>`_ is an Integrated Development
+Environment (IDE) for Python programmers.  It has numerous features including
+code completion, project management, version control system (git, Subversion,
+etc.), debugger, and more.
+
+This tutorial is a continual evolving document. Both PyCharm and Pyramid are
+under active development, and changes to either may necessitate changes to
+this document.  In addition, there may be errors or omissions in this
+document, and corrections and improvements through a pull request are most
+welcome.
+
+To get started with Pyramid in PyCharm, we need to install prerequisite
+software.
+
+* Python
+* PyCharm and certain Python packages
+* Pyramid and its requirements
+
+Install Python
+==============
+
+You can download installers for Mac OS X and Windows, or source tarballs for
+Linux, Unix, or Mac OS X from `python.org Download
+<http://python.org/download/>`_.  Follow the instructions in the README files.
+
+Install PyCharm
+===============
+
+PyCharm is a commercial application that requires a license.  Several license
+types are available depending on your usage.
+
+Pyramid is an open source project, and on an annual basis fulfills the terms of
+the Open Source License with JetBrains for the use of PyCharm to develop for
+Pyramid under the Pylons Project.  If you contribute to Pyramid or the Pylons
+Project, and would like to use our 1-year license, please contact the license
+maintainer `stevepiercy` in the `#pyramid` channel on `irc.freenode.net`.
+
+Alternatively you can download a 30-day trial of PyCharm or `purchase a license
+<http://www.jetbrains.com/pycharm/buy/index.jsp>`_ for development or training
+purposes under any other license.
+
+`Download PyCharm <http://www.jetbrains.com/pycharm/download/index.html>`_ and
+follow the installation instructions on that web page.
+
+Configure PyCharm
+=================
+
+Create a New Project
+--------------------
+
+Launch the PyCharm application.
+
+From the Start Up screen, click Create New Project.
+
+.. image:: images/start_up_screen.png
+
+If the Start Up screen does not appear, you probably have an existing project
+open.  Close the existing project and the Start Up screen will appear.
+
+.. image:: images/create_new_project.png
+
+In the Create New Project dialog window do the following.
+
+* Enter a Project name.  The Location should automatically populate as you
+  type.  You can change the path as you wish.  It is common practice to use the
+  path `~/projects/` to contain projects.  This location shall be referred to
+  as your "project directory" throughout the rest of this document.
+* Project type should be Empty project.
+* For Interpreter, click the ellipsis button to create a new virtual
+  environment.
+
+A new window appears, "Python Interpreters".
+
+Create or Select a Python Interpreter
+-------------------------------------
+
+.. image:: images/python_interpreters_1.png
+
+* Either click the `+` button to add a new Python interpreter for Python
+  2.7 (the Python 2.7 installer uses the path
+  `/Library/Frameworks/Python.framework/Versions/2.7/bin`), or use an existing
+  Python interpreter for Python 2.7.  PyCharm will take a few seconds to add a
+  new interpreter.
+
+.. image:: images/python_interpreters_2.png
+
+Create a Virtual Environment
+----------------------------
+
+* Click the button with the Python logo and a green "V".  A new window appears,
+  "Create Virtual Environment".
+
+.. image:: images/create_virtual_environment.png
+
+* Enter a Virtual Environment name.
+* The Location should automatically populate as you type.  You can change the
+  path as you wish.
+* The Base interpreter should be already selected, but if not, select
+  `/Library/Frameworks/Python.framework/Versions/2.7/bin` or other Python 2.7
+  interpreter.
+* Leave the box unchecked for "Inherit global site packages".
+* Click "OK".  PyCharm will set up libraries and packages, and return you to
+  the Python Interpreters window.
+
+Install setuptools and pyramid Packages
+---------------------------------------
+
+If you already have setuptools installed, you can skip this step.
+
+In the Python Interpreters window with the just-created virtual environment
+selected in the top pane, in the lower pane select the Packages tab, and click
+the Install button.  The Available Packages window appears.
+
+.. image:: images/install_package.png
+
+In the Available Packages window, in the search bar, enter "setuptools". 
+Select the plain old "setuptools" package, and click the Install Package button
+and wait for the status message to disappear.  PyCharm will install the package
+and any dependencies.
+
+.. image:: images/install_package_setuptools.png
+
+Repeat the previous step, except use "pyramid" for searching and selecting.
+
+.. image:: images/install_package_pyramid.png
+
+When PyCharm finishes installing the packages, close the Available Packages
+window.
+
+In the Python Interpreters window, click the OK button.
+
+In the Create New Project window, click the OK button.
+
+If PyCharm displays a warning, click the Yes button.  PyCharm opens the new
+project.
+
+Clone the Pyramid repository
+============================
+
+By cloning the Pyramid repository, you can contribute changes to the code or
+documentation.  We recommend that you fork the Pyramid repository to your own
+GitHub account, then clone your forked repository, so that you can commit your
+changes to your GitHub repository and submit pull requests to the Pyramid
+project.
+
+In PyCharm, select *VCS > Enable Version Control Integration...*, then select
+Git as your VCS and click the OK button.
+
+See `Cloning a Repository from GitHub
+<http://www.jetbrains.com/pycharm/webhelp/cloning-a-repository-from-github.html
+>`_ in the PyCharm documentation for more information on using GitHub and git
+in PyCharm.
+
+We will refer to the cloned repository of Pyramid on your computer as your
+"local Pyramid repository".
+
+Install development and documentation requirements
+==================================================
+
+In order to contribute bug fixes, features, and documentation changes to
+Pyramid, you must install development and documentation requirements into your
+virtual environment.  Pyramid uses Sphinx and reStructuredText for
+documentation.
+
+* In PyCharm, select *Run > Edit Configurations...*.  The Run/Debug
+  Configurations window appears.
+
+    .. image:: images/edit_run_debug_configurations.png
+
+* Click the "+" button, then select Python to add a new Python run
+  configuration.
+* Name the configuration "setup dev".
+* Either manually enter the path to the `setup.py` script or click the ellipsis
+  button to navigate to the `pyramid/setup.py` path and select it.
+* For Script parameters enter `dev`.
+* Click the "Apply" button to save the run configuration.
+
+While we're here, let's duplicate this run configuration for installing the
+documentation requirements.
+
+* Click the "Copy Configuration" button.  Its icon looks like two dog-eared
+  pages, with a blue page on top of a grey page.
+* Name the configuration "setup docs".
+* Leave the path as is.
+* For Script parameters enter `docs`.
+* Click the "Apply" button to save the run configuration.
+* Click the "OK" button to return to the project window.
+
+In the PyCharm toolbar, you will see a Python icon and your run configurations.
+
+.. image:: images/run_configuration.png
+
+First select "setup dev", and click the "run" button (the green triangle).  It
+may take some time to install the requirements.  Second select "setup docs",
+and click the "run" button again.
+
+As of this writing, PyCharm does not yet have a command line interface to a
+shell.  So there are some things that require you to go into a shell to enter
+commands.  This next step requires doing just so.
+
+* In your shell, navigate to your project directory, e.g., `cd
+  ~/projects/pycharm_pyramid/`.
+* Enter the command `source bin/activate` to activate your virtual environment.
+* Navigate into your local Pyramid repository, e.g., `cd pyramid`.
+* Issue the command `git submodule update --init --recursive`.
+* Navigate to the `docs` directory in your local Pyramid repository with the
+  command `cd docs`.
+* Issue the command `make clean html` to generate the HTML documentation from
+  reStructuredText files.
+* The HTML files are in `_build/html`.  Open up `index.html` in a web browser
+  to see the result.
+* Whenever you want to edit existing docs and see the effect of your changes,
+  simply run `make html` from within the `docs` directory.
+
+Unfortunately, the author was unable to figure out how to generate docs in
+PyCharm using either a "Python docs" or "Python" run configuration.  If anyone
+knows, please submit a pull request.
+
+You will now be ready to hack in and contribute to Pyramid.
+
+Template Languages
+==================
+
+To configure the template languages Mako and Jinja, see the PyCharm
+documentation `Templates
+<http://www.jetbrains.com/pycharm/webhelp/templates.html>`_.
+
+To configure the template language Chameleon, see `Creating and Registering
+File Types
+<http://www.jetbrains.com/pycharm/webhelp/creating-and-registering-file-types.
+html>`_.  Specifically for Chameleon, we want to associate XML to the `*.pt`
+extension.
+
+* Open *PyCharm > Preferences...*, then the File Types dialog box.
+* From the Recognized File Types list, select "XML files".
+* In the Registered Patterns area, click the "+" button, and the Add Wildcard
+  window opens.  Enter `*.pt` in the Add Wildcard window, and click the OK
+  button.  Click OK again to save the settings.
+
+Creating a Pyramid Project
+==========================
+
+The information for this section is derived from `Creating a Pyramid Project
+<http://docs.pylonsproject.org/projects/pyramid/en/master/narr/project.html>`_
+and adapted for use in PyCharm.
+
+Creating a Pyramid Project Using Scaffolds
+------------------------------------------
+
+Within PyCharm, you can start a project using a scaffold by doing the
+following.
+
+* Select *Run > Edit Configurations...*.
+* Click the "+" button, then select Python to add a new Python run
+  configuration.
+* Name the configuration "pcreate".
+* Either manually enter the path to the `pcreate` script or click the ellipsis
+  button to navigate to the `$VENV/bin/pcreate` path and select it.
+* For Script parameters enter `-s starter MyProject`.  "starter" is the name of
+  one of the scaffolds included with Pyramid, but you can use any scaffold.
+  "MyProject" is the name of your project.
+* Select the directory into which you want to place `MyProject`.  A common
+  practice is `~/projects/`.
+* Click the OK button to save the run configuration.
+* Select *Run > Run 'pcreate'* to run the run configuration.  Your project will
+  be created.
+* Select *File > Open directory*, select the directory where you created your
+  project `MyProject`, and click the Choose button.  You will be prompted to
+  open the project, and you may find it convenient to select "Open in current
+  window", and check "Add to currently open projects".
+* Finally set the Project Interpreter to your virtual environment or verify it
+  as such.  Select *PyCharm > Preferences... > Project Interpreter*, and verify
+  that the project is using the same virtual environment as the parent project.
+* If a yellow bar warns you to install requirements, then click link to do so.
+
+Installing your Newly Created Project for Development
+-----------------------------------------------------
+
+We will create another run configuration, just like before.
+
+* In PyCharm, select the `setup.py` script in the `MyProject` folder.  This
+  should populate some fields with the proper values.
+* Select *Run > Edit Configurations...*.
+* Click the "+" button, then select Python to add a new Python run
+  configuration.
+* Name the configuration "MyProject setup develop".
+* Either manually enter the path to the `setup.py` script in the `MyProject`
+  folder or click the ellipsis button to navigate to the path and select it.
+* For Script parameters enter `develop`.
+* For Project, select "MyProject".
+* For Working directory, enter or select the path to `MyProject`.
+* Click the "Apply" button to save the run configuration.
+* Finally run the run configuration "MyProject setup develop".  Your project
+  will be installed.
+
+Running The Tests For Your Application
+--------------------------------------
+
+We will create yet another run configuration.  [If you know of an easier method
+while in PyCharm, please submit a pull request.]
+
+* Select *Run > Edit Configurations...*.
+* Select the previous run configuration "MyProject setup develop", and click
+  the Copy Configuration button.
+* Name the configuration "MyProject setup test".
+* The path to the `setup.py` script in the `MyProject` folder should already be
+  entered.
+* For Script parameters enter `test -q`.
+* For Project "MyProject" should be selected.
+* For Working directory, the path to `MyProject` should be selected.
+* Click the "Apply" button to save the run configuration.
+* Finally run the run configuration "MyProject setup test".  Your project will
+  run its unit tests.
+
+Running The Project Application
+-------------------------------
+
+When will creation of run configurations end?  Not today!
+
+* Select *Run > Edit Configurations...*.
+* Select the previous run configuration "MyProject setup develop", and click
+  the Copy Configuration button.
+* Name the configuration "MyProject pserve".
+* Either manually enter the path to the `pserve` script or click the ellipsis
+  button to navigate to the `$VENV/bin/pserve` path and select it.
+* For Script parameters enter `development.ini`.
+* For Project "MyProject" should be selected.
+* For Working directory, the path to `MyProject` should be selected.
+* Click the "Apply" button to save the run configuration.
+* Finally run the run configuration "MyProject pserve".  Your project will run.
+  Click the link in the Python console or visit the URL http://0.0.0.0:6543/ in
+  a web browser.
+
+You can also reload any changes to your project's `.py` or `.ini` files
+automatically by using the Script parameters `development.ini --reload`.
+
+Debugging
+=========
+
+See the PyCharm documentation `Running and Debugging
+<http://www.jetbrains.com/pycharm/webhelp/running-and-debugging.html>`_ for
+details on how to debug your Pyramid app in PyCharm.
+
+First, you cannot simultaneously run and debug your app.  Terminate your app if
+it is running before you debug it.
+
+To debug your app, open a file in your app that you want to debug and click on
+the gutter (the space between line numbers and the code) to set a breakpoint. 
+Then select "MyProject pserve" in the PyCharm toolbar, then click the debug
+icon (which looks like a green ladybug).  Your app will run up to the first
+breakpoint.