diff options
15 files changed, 18 insertions, 369 deletions
diff --git a/docs/authorintro.rst b/docs/authorintro.rst index f1a9d1484..b3cd68494 100644 --- a/docs/authorintro.rst +++ b/docs/authorintro.rst @@ -73,7 +73,7 @@ This book is divided into three major parts: concepts in terms of the sample. You should read the tutorials if you want a guided tour of :app:`Pyramid`. -:ref:`api_reference` +:ref:`api_documentation` Comprehensive reference material for every public API exposed by :app:`Pyramid`. The API documentation is organized diff --git a/docs/index.rst b/docs/index.rst index 35646f3d2..4be0ecd26 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,7 +46,7 @@ What's New .. _html_narrative_documentation: -Narrative documentation +Narrative Documentation ======================= Narrative documentation in chapter form explaining how to use @@ -112,7 +112,7 @@ platforms. tutorials/pycharm/index.rst API Documentation -================== +================= Comprehensive reference material for every public API exposed by :app:`Pyramid`: diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 6bb875f73..416fc9bf1 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -1,13 +1,13 @@ .. _latexindex: -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ -The :app:`Pyramid` Web Application Framework -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +================================================= +The Pyramid Web Application Development Framework +================================================= .. frontmatter:: Front Matter -@@@@@@@@@@@@ +============ .. toctree:: :maxdepth: 1 @@ -21,15 +21,15 @@ Front Matter .. _narrative_documentation: Narrative Documentation -@@@@@@@@@@@@@@@@@@@@@@@ +======================= .. toctree:: :maxdepth: 1 narr/introduction narr/install - narr/configuration narr/firstapp + narr/configuration narr/project narr/startup narr/router @@ -50,6 +50,7 @@ Narrative Documentation narr/vhosting narr/testing narr/resources + narr/hellotraversal narr/muchadoabouttraversal narr/traversal narr/security @@ -60,26 +61,29 @@ Narrative Documentation narr/extending narr/advconfig narr/extconfig + narr/scaffolding + narr/upgrading narr/threadlocals narr/zca .. _tutorials: Tutorials -@@@@@@@@@ +========= .. toctree:: :maxdepth: 1 - tutorials/wiki/index.rst tutorials/wiki2/index.rst + tutorials/wiki/index.rst tutorials/bfg/index.rst tutorials/modwsgi/index.rst + tutorials/pycharm/index.rst -.. _api_reference: +.. _api_documentation: -API Reference -@@@@@@@@@@@@@ +API Documentation +================= .. toctree:: :maxdepth: 1 diff --git a/docs/tutorials/pycharm/images/create_new_project.png b/docs/tutorials/pycharm/images/create_new_project.png Binary files differdeleted file mode 100644 index f15068b65..000000000 --- a/docs/tutorials/pycharm/images/create_new_project.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/create_setup.png b/docs/tutorials/pycharm/images/create_setup.png Binary files differdeleted file mode 100644 index de4cb364b..000000000 --- a/docs/tutorials/pycharm/images/create_setup.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/create_virtual_environment.png b/docs/tutorials/pycharm/images/create_virtual_environment.png Binary files differdeleted file mode 100644 index 0bd3c9263..000000000 --- a/docs/tutorials/pycharm/images/create_virtual_environment.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/edit_run_debug_configurations.png b/docs/tutorials/pycharm/images/edit_run_debug_configurations.png Binary files differdeleted file mode 100644 index 7708fa9dc..000000000 --- a/docs/tutorials/pycharm/images/edit_run_debug_configurations.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/install_package.png b/docs/tutorials/pycharm/images/install_package.png Binary files differdeleted file mode 100644 index 944a05f6a..000000000 --- a/docs/tutorials/pycharm/images/install_package.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/install_package_pyramid.png b/docs/tutorials/pycharm/images/install_package_pyramid.png Binary files differdeleted file mode 100644 index 05a209b6c..000000000 --- a/docs/tutorials/pycharm/images/install_package_pyramid.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/install_package_setuptools.png b/docs/tutorials/pycharm/images/install_package_setuptools.png Binary files differdeleted file mode 100644 index 8932a3f40..000000000 --- a/docs/tutorials/pycharm/images/install_package_setuptools.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/python_interpreters_1.png b/docs/tutorials/pycharm/images/python_interpreters_1.png Binary files differdeleted file mode 100644 index 6b1455001..000000000 --- a/docs/tutorials/pycharm/images/python_interpreters_1.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/python_interpreters_2.png b/docs/tutorials/pycharm/images/python_interpreters_2.png Binary files differdeleted file mode 100644 index 61c3de2b1..000000000 --- a/docs/tutorials/pycharm/images/python_interpreters_2.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/run_configuration.png b/docs/tutorials/pycharm/images/run_configuration.png Binary files differdeleted file mode 100644 index 4612b2b3c..000000000 --- a/docs/tutorials/pycharm/images/run_configuration.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/start_up_screen.png b/docs/tutorials/pycharm/images/start_up_screen.png Binary files differdeleted file mode 100644 index c65e01eeb..000000000 --- a/docs/tutorials/pycharm/images/start_up_screen.png +++ /dev/null diff --git a/docs/tutorials/pycharm/index.rst b/docs/tutorials/pycharm/index.rst deleted file mode 100644 index f2e3b7bcb..000000000 --- a/docs/tutorials/pycharm/index.rst +++ /dev/null @@ -1,355 +0,0 @@ -************************** -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. |
