From 5ded35a5d057eb6188d6f80c47593ec934833d47 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2013 21:32:14 -0700 Subject: - straighten out difference between content and its presentation, re: admonitions of note, seealse, sidebar --- docs/narr/project.rst | 79 +++++++++++++++++++++------------------------------ 1 file changed, 33 insertions(+), 46 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index b4397c09b..fcce9fac4 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -146,7 +146,7 @@ puts his projects in ``C:\projects``. .. warning:: - You’ll need to avoid using ``pcreate`` to create a project with the same + You'll need to avoid using ``pcreate`` to create a project with the same name as a Python standard library component. In particular, this means you should avoid using the names ``site`` or ``test``, both of which conflict with Python standard library packages. You should also avoid @@ -210,12 +210,6 @@ Python interpreter from the :term:`virtualenv` you created during :ref:`installing_chapter` (the ``python`` command that lives in the ``bin`` directory of your virtualenv). -.. sidebar:: Verbose Testing - - The ``-q`` option is passed to the ``setup.py test`` command to limit the - output to a stream of dots. If you don't pass ``-q``, you'll see more - verbose test result output (which normally isn't very useful). - On UNIX: .. code-block:: text @@ -253,6 +247,12 @@ The tests themselves are found in the ``tests.py`` module in your ``pcreate`` generated project. Within a project generated by the ``starter`` scaffold, a single sample test exists. +.. note:: + + The ``-q`` option is passed to the ``setup.py test`` command to limit the + output to a stream of dots. If you don't pass ``-q``, you'll see more + verbose test result output (which normally isn't very useful). + .. index:: single: running an application single: pserve @@ -684,14 +684,6 @@ use a different version control system, you may need to install a setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. -.. sidebar:: Python's ``setup.py`` - - ``setup.py`` is the de facto standard which Python developers use to - distribute their reusable code. You can read more about ``setup.py`` files - and their usage in the `Setuptools documentation - `_ and `The - Hitchhiker's Guide to Packaging `_. - .. index:: single: setup.py @@ -702,6 +694,14 @@ The ``setup.py`` file is a :term:`setuptools` setup file. It is meant to be run directly from the command line to perform a variety of functions, such as testing, packaging, and distributing your application. +.. note:: + + ``setup.py`` is the de facto standard which Python developers use to + distribute their reusable code. You can read more about ``setup.py`` files + and their usage in the `Setuptools documentation + `_ and `The + Hitchhiker's Guide to Packaging `_. + Our generated ``setup.py`` looks like this: .. literalinclude:: MyProject/setup.py @@ -857,26 +857,6 @@ and which returns a :term:`response`. :language: python :linenos: -.. sidebar:: Fully Interactive Development - - Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to - increase template rendering speed. - - Pyramid can also dynamically reload changed Python files. For more - on this see :ref:`reloading_code` above. - - The :ref:`debug_toolbar` provides interactive access to your - application's internals and, should an exception occur, allows - interactive access to traceback execution stack frames from the - Python interpreter. - Lines 4-6 define and register a :term:`view callable` named ``my_view``. The function named ``my_view`` is decorated with a ``view_config`` decorator (which is processed by the ``config.scan()`` line in our ``__init__.py``). @@ -905,20 +885,27 @@ returns the HTML in a :term:`response`. .. note:: Dictionaries provide values to :term:`template`\s. -See :ref:`views_which_use_a_renderer` for more information about how views, -renderers, and templates relate and cooperate. - .. note:: ``development.ini`` has a setting that controls how templates are - reloaded: ``pyramid.reload_templates``. - - - A setting of ``True`` (as in the scaffold ``development.ini``) - automatically reloads changed templates without a server restart. This - is convenient while developing but slows template rendering speed. - - - A setting of ``False`` (the default) requires a server restart to - integrate template changes. Production applications should set + reloaded, ``pyramid.reload_templates``. + + - 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. + + - When set to ``False`` (the default value), changing templates requires + a server restart to reload them. Production applications should use ``pyramid.reload_templates = False``. +.. seealso:: See also :ref:`views_which_use_a_renderer` for more information + about how views, renderers, and templates relate and cooperate. + +.. seealso:: Pyramid can also dynamically reload changed Python files. For + more on this see :ref:`reloading_code`. + +.. seealso:: The :ref:`debug_toolbar` provides interactive access to your + application's internals and, should an exception occur, allows interactive + access to traceback execution stack frames from the Python interpreter. + .. index:: single: static directory -- cgit v1.2.3