diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/project.rst | 80 |
1 files changed, 41 insertions, 39 deletions
diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 76c56157a..d8312b4ea 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -470,7 +470,7 @@ which contains a Python :term:`package`. The package is *also* named ``myproject``, but it's lowercased; the scaffold generates a project which contains a package that shares its name except for case. -All :app:`Pyramid` ``pcreate`` -generated projects share a similar structure. +All :app:`Pyramid` ``pcreate``-generated projects share a similar structure. The ``MyProject`` project we've generated has the following directory structure: @@ -542,7 +542,7 @@ The generated ``development.ini`` file looks like so: :linenos: This file contains several sections including ``[app:main]``, -``[server:main]`` and several other sections related to logging +``[server:main]``, and several other sections related to logging configuration. The ``[app:main]`` section represents configuration for your :app:`Pyramid` @@ -554,11 +554,11 @@ to the function named ``main`` in our package's ``__init__.py`` module. You can provide startup-time configuration parameters to your application by adding more settings to this section. -.. note:: See :ref:`pastedeploy_entry_points` for more information about the +.. seealso:: See :ref:`pastedeploy_entry_points` for more information about the meaning of the ``use = egg:MyProject`` value in this section. The ``pyramid.reload_templates`` setting in the ``[app:main]`` section is a -:app:`Pyramid` -specific setting which is passed into the framework. If it +:app:`Pyramid`-specific setting which is passed into the framework. If it exists, and its value is ``true``, supported template changes will not require an application restart to be detected. See :ref:`reload_templates_section` for more information. @@ -571,9 +571,10 @@ The ``pyramid.includes`` setting in the ``[app:main]`` section tells Pyramid to "include" configuration from another package. In this case, the line ``pyramid.includes = pyramid_debugtoolbar`` tells Pyramid to include configuration from the ``pyramid_debugtoolbar`` package. This turns on a -debugging panel in development mode which will be shown on the right hand -side of the screen. Including the debug toolbar will also make it possible -to interactively debug exceptions when an error occurs. +debugging panel in development mode which can be opened by clicking on the +:app:`Pyramid` logo on the top right of the screen. Including the debug +toolbar will also make it possible to interactively debug exceptions when an +error occurs. Various other settings may exist in this section having to do with debugging or influencing runtime behavior of a :app:`Pyramid` application. See @@ -597,14 +598,14 @@ and ``# End logging configuration`` represent Python's standard library between these two markers are passed to the `logging module's config file configuration engine <http://docs.python.org/howto/logging.html#configuring-logging>`_ when the -``pserve`` or ``pshell`` commands are executed. The default -configuration sends application logging output to the standard error output -of your terminal. For more information about logging configuration, see +``pserve`` or ``pshell`` commands are executed. The default configuration +sends application logging output to the standard error output of your +terminal. For more information about logging configuration, see :ref:`logging_chapter`. See the :term:`PasteDeploy` documentation for more information about other types of things you can put into this ``.ini`` file, such as other -applications, :term:`middleware` and alternate :term:`WSGI` server +applications, :term:`middleware`, and alternate :term:`WSGI` server implementations. .. index:: @@ -736,7 +737,7 @@ For fun, you can try this command now: .. code-block:: text - $ python setup.py sdist + $ $VENV/bin/python setup.py sdist This will create a tarball of your application in a ``dist`` subdirectory named ``MyProject-0.1.tar.gz``. You can send this tarball to other people @@ -765,11 +766,10 @@ The ``myproject`` :term:`package` lives inside the ``MyProject`` #. A ``views.py`` module, which contains view code for the application. -These are purely conventions established by the scaffold: -:app:`Pyramid` doesn't insist that you name things in any particular way. -However, it's generally a good idea to follow Pyramid standards for naming, -so that other Pyramid developers can get up to speed quickly on your code -when you need help. +These are purely conventions established by the scaffold. :app:`Pyramid` +doesn't insist that you name things in any particular way. However, it's +generally a good idea to follow Pyramid standards for naming, so that other +Pyramid developers can get up to speed quickly on your code when you need help. .. index:: single: __init__.py @@ -839,13 +839,13 @@ The view_config decorator asserts that this view be found when a route will match when a visitor visits the root URL. The view_config decorator also names a ``renderer``, which in this case is a template that will be used to render the result of the view callable. This particular view -declaration points at ``templates/mytemplate.pt``, which is a :term:`asset +declaration points at ``templates/mytemplate.pt``, which is an :term:`asset specification` that specifies the ``mytemplate.pt`` file within the ``templates`` directory of the ``myproject`` package. The asset specification could have also been specified as ``myproject:templates/mytemplate.pt``; the leading package name and colon is -optional. The template file pointed to is a :term:`Chameleon` ZPT -template file (``templates/my_template.pt``). +optional. The template file pointed to is a :term:`Chameleon` ZPT template +file (``templates/my_template.pt``). This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` @@ -859,7 +859,7 @@ returns the HTML in a :term:`response`. .. note:: Dictionaries provide values to :term:`template`\s. .. note:: When the application is run with the scaffold's :ref:`default - development.ini <MyProject_ini>` configuration :ref:`logging is set up + development.ini <MyProject_ini>` configuration, :ref:`logging is set up <MyProject_ini_logging>` to aid debugging. If an exception is raised, uncaught tracebacks are displayed after the startup messages on :ref:`the console running the server <running_the_project_application>`. Also @@ -869,7 +869,7 @@ returns the HTML in a :term:`response`. .. note:: ``development.ini`` has a setting that controls how templates are reloaded, ``pyramid.reload_templates``. - - When set to ``True`` (as in the scaffold ``development.ini``) changed + - When set to ``True`` (as in the scaffold ``development.ini``), changed templates automatically reload without a server restart. This is convenient while developing, but slows template rendering speed. @@ -906,7 +906,7 @@ template. It includes CSS and images. ``templates/mytemplate.pt`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The single :term:`Chameleon` template that exists in the project. Its +This is the single :term:`Chameleon` template that exists in the project. Its contents are too long to show here, but it displays a default page when rendered. It is referenced by the call to ``@view_config`` as the ``renderer`` of the ``my_view`` view callable in the ``views.py`` file. See @@ -926,12 +926,13 @@ The ``tests.py`` module includes unit tests for your application. .. literalinclude:: MyProject/myproject/tests.py :language: python + :lines: 1-18 :linenos: This sample ``tests.py`` file has a single unit test defined within it. This test is executed when you run ``python setup.py test``. You may add more tests here as you build your application. You are not required to write -tests to use :app:`Pyramid`, this file is simply provided as convenience and +tests to use :app:`Pyramid`. This file is simply provided for convenience and example. See :ref:`testing_chapter` for more information about writing :app:`Pyramid` @@ -963,7 +964,8 @@ adding a single file for each view. If your project package name was ``myproject`` and you wanted to arrange all your views in a Python subpackage within the ``myproject`` :term:`package` -named ``views`` instead of within a single ``views.py`` file, you might: +named ``views`` instead of within a single ``views.py`` file, you might do the +following. - Create a ``views`` directory inside your ``myproject`` package directory (the same directory which holds ``views.py``). @@ -982,8 +984,8 @@ You can then continue to add view callable functions to the ``blog.py`` module, but you can also add other ``.py`` files which contain view callable functions to the ``views`` directory. As long as you use the ``@view_config`` directive to register views in conjunction with -``config.scan()`` they will be picked up automatically when the application -is restarted. +``config.scan()``, they will be picked up automatically when the application is +restarted. Using the Interactive Shell --------------------------- @@ -998,22 +1000,22 @@ See :ref:`interactive_shell` for more details. What Is This ``pserve`` Thing ----------------------------- -The code generated by an :app:`Pyramid` scaffold assumes that you will be -using the ``pserve`` command to start your application while you do -development. ``pserve`` is a command that reads a :term:`PasteDeploy` -``.ini`` file (e.g. ``development.ini``) and configures a server to serve a -Pyramid application based on the data in the file. +The code generated by a :app:`Pyramid` scaffold assumes that you will be using +the ``pserve`` command to start your application while you do development. +``pserve`` is a command that reads a :term:`PasteDeploy` ``.ini`` file (e.g., +``development.ini``), and configures a server to serve a :app:`Pyramid` +application based on the data in the file. ``pserve`` is by no means the only way to start up and serve a :app:`Pyramid` application. As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be invoked at all to run a :app:`Pyramid` application. The use of ``pserve`` to -run a :app:`Pyramid` application is purely conventional based on the output -of its scaffolding. But we strongly recommend using ``pserve`` while -developing your application, because many other convenience introspection -commands (such as ``pviews``, ``prequest``, ``proutes`` and others) are also -implemented in terms of configuration availability of this ``.ini`` file -format. It also configures Pyramid logging and provides the ``--reload`` -switch for convenient restarting of the server when code changes. +run a :app:`Pyramid` application is purely conventional based on the output of +its scaffolding. But we strongly recommend using ``pserve`` while developing +your application because many other convenience introspection commands (such as +``pviews``, ``prequest``, ``proutes``, and others) are also implemented in +terms of configuration availability of this ``.ini`` file format. It also +configures Pyramid logging and provides the ``--reload``switch for convenient +restarting of the server when code changes. .. _alternate_wsgi_server: |