From 4042c772c8043ac96a22db439a736fec9ea2aafa Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 17:09:35 -0400 Subject: All the references re-wired. --- docs/conf.py | 30 ------ docs/quick_tutorial/authentication.rst | 6 +- docs/quick_tutorial/authorization.rst | 2 +- docs/quick_tutorial/hello_world.rst | 14 +-- docs/quick_tutorial/index.rst | 2 +- docs/quick_tutorial/ini.rst | 14 +-- docs/quick_tutorial/json.rst | 6 +- docs/quick_tutorial/logging.rst | 2 +- docs/quick_tutorial/more_view_classes.rst | 6 +- docs/quick_tutorial/pyramid_setup.rst | 24 ++--- docs/quick_tutorial/python_setup.rst | 97 +++++------------ docs/quick_tutorial/request_response.rst | 6 +- docs/quick_tutorial/rest_ajax.rst | 62 ----------- docs/quick_tutorial/rest_ajax_layout.rst | 50 --------- docs/quick_tutorial/rest_bootstrap.rst | 88 --------------- docs/quick_tutorial/routing.rst | 4 +- docs/quick_tutorial/sessions.rst | 8 +- docs/quick_tutorial/static_assets.rst | 6 +- docs/quick_tutorial/templating.rst | 8 +- docs/quick_tutorial/traversal_addcontent.rst | 105 ------------------ docs/quick_tutorial/traversal_hierarchy.rst | 106 ------------------- docs/quick_tutorial/traversal_siteroot.rst | 153 --------------------------- docs/quick_tutorial/traversal_typeviews.rst | 112 -------------------- docs/quick_tutorial/traversal_zodb.rst | 121 --------------------- docs/quick_tutorial/unit_testing.rst | 2 +- docs/quick_tutorial/view_classes.rst | 4 +- docs/quick_tutorial/views.rst | 10 +- 27 files changed, 84 insertions(+), 964 deletions(-) delete mode 100644 docs/quick_tutorial/rest_ajax.rst delete mode 100644 docs/quick_tutorial/rest_ajax_layout.rst delete mode 100644 docs/quick_tutorial/rest_bootstrap.rst delete mode 100644 docs/quick_tutorial/traversal_addcontent.rst delete mode 100644 docs/quick_tutorial/traversal_hierarchy.rst delete mode 100644 docs/quick_tutorial/traversal_siteroot.rst delete mode 100644 docs/quick_tutorial/traversal_typeviews.rst delete mode 100644 docs/quick_tutorial/traversal_zodb.rst (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 799ec7820..ee852aa51 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -90,39 +90,9 @@ intersphinx_mapping = { 'zcml': ('http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest', None), - 'pyramid': ( - 'http://docs.pylonsproject.org/projects/pyramid/en/latest/', - None) } -#intersphinx_mapping = { -# 'python': ( -# 'http://docs.python.org/2', -# None), -# 'sqla': ( -# 'http://docs.sqlalchemy.org/en/latest', -# None), -# 'pyramid': ( -# 'http://docs.pylonsproject.org/projects/pyramid/en/latest/', -# None), -# 'jinja2': ( -# 'http://docs.pylonsproject.org/projects/pyramid_jinja2/en/latest/', -# None), -# 'toolbar': ( -# 'http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest', -# None), -# 'deform': ( -# 'http://docs.pylonsproject.org/projects/deform/en/latest', -# None), -# 'colander': ( -# 'http://docs.pylonsproject.org/projects/colander/en/latest', -# None), -# 'tutorials': ( -# 'http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/', -# None), -#} - # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/quick_tutorial/authentication.rst b/docs/quick_tutorial/authentication.rst index 6b9b5fafc..aaebba7ea 100644 --- a/docs/quick_tutorial/authentication.rst +++ b/docs/quick_tutorial/authentication.rst @@ -102,7 +102,7 @@ one step at a time, we provide a system that identifies users and lets them log out. In this example we chose to use the bundled -:ref:`AuthTktAuthenticationPolicy ` +:ref:`AuthTktAuthenticationPolicy ` policy. We enabled it in our configuration and provided a ticket-signing secret in our INI file. @@ -130,5 +130,5 @@ Extra Credit onto each request? Use ``import pdb; pdb.set_trace()`` to answer this. -.. seealso:: :ref:`pyramid:security_chapter`, - :ref:`AuthTktAuthenticationPolicy ` +.. seealso:: :ref:`security_chapter`, + :ref:`AuthTktAuthenticationPolicy ` diff --git a/docs/quick_tutorial/authorization.rst b/docs/quick_tutorial/authorization.rst index 37b1a0520..9acd3b4a5 100644 --- a/docs/quick_tutorial/authorization.rst +++ b/docs/quick_tutorial/authorization.rst @@ -41,7 +41,7 @@ Steps (env27)$ python setup.py develop #. Start by changing ``authorization/tutorial/__init__.py`` to - specify a root factory to the :term:`pyramid:configurator`: + specify a root factory to the :term:`configurator`: .. literalinclude:: authorization/tutorial/__init__.py :linenos: diff --git a/docs/quick_tutorial/hello_world.rst b/docs/quick_tutorial/hello_world.rst index e44ef616d..e3ad820ac 100644 --- a/docs/quick_tutorial/hello_world.rst +++ b/docs/quick_tutorial/hello_world.rst @@ -70,19 +70,19 @@ explanation: #. *Line 11*. The ``if __name__ == '__main__':`` is Python's way of saying "Start here when running from the command line". -#. *Lines 12-14*. Use Pyramid's :term:`pyramid:configurator` to connect - :term:`pyramid:view` code to a particular URL - :term:`pyramid:route`. +#. *Lines 12-14*. Use Pyramid's :term:`configurator` to connect + :term:`view` code to a particular URL + :term:`route`. #. *Lines 6-7*. Implement the view code that generates the - :term:`pyramid:response`. + :term:`response`. -#. *Lines 15-17*. Publish a :term:`pyramid:WSGI` app using an HTTP +#. *Lines 15-17*. Publish a :term:`WSGI` app using an HTTP server. -As shown in this example, the :term:`pyramid:configurator` plays a +As shown in this example, the :term:`configurator` plays a central role in Pyramid development. Building an application from -loosely-coupled parts via :ref:`pyramid:configuration_narr` is a +loosely-coupled parts via :ref:`configuration_narr` is a central idea in Pyramid, one that we will revisit regularly in this *Quick Tour*. diff --git a/docs/quick_tutorial/index.rst b/docs/quick_tutorial/index.rst index 9d32f9a81..857364731 100644 --- a/docs/quick_tutorial/index.rst +++ b/docs/quick_tutorial/index.rst @@ -5,7 +5,7 @@ Quick Tutorial for Pyramid ========================== Pyramid is a web framework for Python 2 and 3. This tutorial gives a -Python 2/3-compatible, high-level tour of the major features. +Python 3/2-compatible, high-level tour of the major features. This hands-on tutorial covers "a little about a lot": practical introductions to the most common facilities. Fun, fast-paced, and most diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index 85b07812e..66247c92d 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -9,7 +9,7 @@ Background ========== Pyramid has a first-class concept of -:ref:`configuration ` distinct from code. +:ref:`configuration ` distinct from code. This approach is optional, but its presence makes it distinct from other Python web frameworks. It taps into Python's ``setuptools`` library, which establishes conventions for how Python projects can be @@ -82,7 +82,7 @@ Analysis Our ``development.ini`` file is read by ``pserve`` and serves to bootstrap our application. Processing then proceeds as described in the Pyramid chapter on -:ref:`application startup `: +:ref:`application startup `: - ``pserve`` looks for ``[app:main]`` and finds ``use = egg:tutorial`` @@ -132,11 +132,11 @@ Extra Credit it the ``main`` function. Why not? .. seealso:: - :ref:`pyramid:project_narr`, - :ref:`pyramid:scaffolding_chapter`, - :ref:`pyramid:what_is_this_pserve_thing`, - :ref:`pyramid:environment_chapter`, - :ref:`pyramid:paste_chapter` + :ref:`project_narr`, + :ref:`scaffolding_chapter`, + :ref:`what_is_this_pserve_thing`, + :ref:`environment_chapter`, + :ref:`paste_chapter` Extra Credit ============ diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst index 213de8364..f08db6849 100644 --- a/docs/quick_tutorial/json.rst +++ b/docs/quick_tutorial/json.rst @@ -96,6 +96,6 @@ Python can't natively JSON encode DateTime objects. There are a number of solutions for this in Pyramid, including extending the JSON renderer with a custom renderer. -.. seealso:: :ref:`pyramid:views_which_use_a_renderer`, - :ref:`pyramid:json_renderer`, and - :ref:`pyramid:adding_and_overriding_renderers` +.. seealso:: :ref:`views_which_use_a_renderer`, + :ref:`json_renderer`, and + :ref:`adding_and_overriding_renderers` diff --git a/docs/quick_tutorial/logging.rst b/docs/quick_tutorial/logging.rst index a81b961b0..e68cd536b 100644 --- a/docs/quick_tutorial/logging.rst +++ b/docs/quick_tutorial/logging.rst @@ -74,4 +74,4 @@ visit ``http://localhost:6543`` your console will now show:: Also, if you have configured your Pyramid application to use the ``pyramid_debugtoolbar``, logging statements appear in one of its menus. -.. seealso:: See Also: :ref:`pyramid:logging_chapter` +.. seealso:: See Also: :ref:`logging_chapter` diff --git a/docs/quick_tutorial/more_view_classes.rst b/docs/quick_tutorial/more_view_classes.rst index b01e17a67..4a4b62683 100644 --- a/docs/quick_tutorial/more_view_classes.rst +++ b/docs/quick_tutorial/more_view_classes.rst @@ -20,7 +20,7 @@ So far our views have been simple, free-standing functions. Many times your views are related: different ways to look at or work on the same data or a REST API that handles multiple operations. Grouping these together as a -:ref:`view class ` makes sense: +:ref:`view class ` makes sense: - Group views @@ -29,7 +29,7 @@ together as a - Share some state and helpers Pyramid views have -:ref:`view predicates ` that +:ref:`view predicates ` that help determine which view is matched to a request. These predicates provide many axes of flexibility. @@ -176,5 +176,5 @@ Extra Credit #. There is also a ``request.route_path`` API. How does this differ from ``request.route_url``? -.. seealso:: :ref:`pyramid:class_as_view`, `Weird Stuff You Can Do With +.. seealso:: :ref:`class_as_view`, `Weird Stuff You Can Do With URL Dispatch `_ diff --git a/docs/quick_tutorial/pyramid_setup.rst b/docs/quick_tutorial/pyramid_setup.rst index 5efcc7dc7..187a25adf 100644 --- a/docs/quick_tutorial/pyramid_setup.rst +++ b/docs/quick_tutorial/pyramid_setup.rst @@ -2,26 +2,14 @@ Pyramid Setup ============= -Installing Pyramid is easy and normal from a Python packaging -perspective. Again, *make sure* you have your virtual environment first -in your path using ``source bin/activate``. +We now have a standard starting point for Python. Getting Pyramid +installed is easy: .. code-block:: bash - (env27)$ easy_install pyramid - ....chuggalugga... - (env27ß)$ which pserve + $ easy_install pyramid -You now have Pyramid installed. The second command confirms this by -looking for the Pyramid ``pserve`` command that should be on your -``$PATH`` in the ``bin`` of your virtual environment. +Our virtual environment now has the Pyramid software available to its +Python. -Installing Everything -===================== - -Later parts of the tutorial install more packages. Most likely, -you'd like to go ahead and get much of it now: - -.. code-block:: bash - - (env27)$ easy_install pyramid nose webtest deform sqlalchemy \ No newline at end of file +.. seealso:: See Also: :ref:`installing_unix` diff --git a/docs/quick_tutorial/python_setup.rst b/docs/quick_tutorial/python_setup.rst index 2d56a0327..5ac32dc97 100644 --- a/docs/quick_tutorial/python_setup.rst +++ b/docs/quick_tutorial/python_setup.rst @@ -2,87 +2,46 @@ Python Setup ============ -First things first: we need our Python environment in ship-shape. -Pyramid encourages standard Python development practices (virtual -environments, packaging tools, logging, etc.) so let's get our working -area in place. - .. note:: - This tutorial is aimed at Python 2.7. It also works with - Python 3.3. - -*This step has most likely been performed already on the CCDC computers.* - -Prequisites -=========== + This tutorial is aimed at Python 3.3. It also works with + Python 2.7. -Modern Python development means two tools to add to the standard -Python installation: packaging and virtual environments. - -Python's tools for installing packages is undergoing rapid change. For -this tutorial, we will install the latest version of -`setuptools `_. This gives us -the ``easy_install`` command-line tool for installing Python packages. -Presuming you have Python on your ``PATH``: +First thing's first: we need our Python environment in ship-shape. +Pyramid encourages standard Python development practices (virtual +environments, packaging tools, logging, etc.) so let's get our working +area in place. For Python 3.3: .. code-block:: bash + $ pyvenv-3.3 env33 + $ source env33/bin/activate $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python -We now have an ``easy_install`` command that we can use to install -``virtualenv``: - -.. code-block:: bash - - $ easy_install virtualenv - -Making a Virtual Environment -============================ - -Developing in isolation helps us ensure what we are learning doesn't -conflict with any packages installed from other work on the machine. -*Virtual environments* let us do just this. - -Presuming you have made a tutorial area at some location (referenced as -``your/tutorial/directory`` below): +If ``wget`` complains with a certificate error, run it with: .. code-block:: bash - $ cd your/tutorial/directory - $ virtualenv env27 - $ source env27/bin/activate - (env27)$ which python2.7 + $ wget --no-check-certificate -Once you do this, your path will be setup to point at the ``bin`` of -your virtual environment. Your prompt will also change, as noted above. +In these steps above we first made a :term:`virtualenv` and then +"activated" it, which adjusted our path to look first in +``env33/bin`` for commands (such as ``python``). We next downloaded +Python's packaging support and installed it, giving us the +``easy_install`` command-line script for adding new packages. Python +2.7 users will need to use ``virtualenv`` instead of ``pyvenv`` to make +their virtual environment. .. note:: - This tutorial presumes you are working in a command-line shell - which has performed the ``source env27/bin/activate``. If you - close that shell, or open a new one, you will need to re-perform - that command. - -Discussion -========== - -The modern world of Python packaging eschews ``easy_install`` in favor -of ``pip``, a more-recent and maintained packaging tool. Why doesn't -this tutorial use it? - -- ``pip`` is only gradually getting the ability to install Windows - binaries. ``easy_install`` has been able to do this for years. - -- Until recently, ``pip`` has not been able to use "namespace - packages." As the ``pip`` support for this stabilizes, - we can switch to using ``pip``. - -- You have to use ``easy_install`` to get ``pip`` installed, so why not - just stick with ``easy_install``. - -Python 3.3 has a `built-in story for virtual -environments `_. This -eliminates the requirement for installing ``virtualenv``. Instead, -Python 3.3 provides the ``pyvenv`` command for creating virtual -environments. \ No newline at end of file + Why ``easy_install`` and not ``pip``? Pyramid encourages use of + namespace packages which, until recently, ``pip`` didn't permit. + Also, Pyramid has some optional C extensions for performance. With + ``easy_install``, Windows users can get these extensions without + needing a C compiler. + +.. seealso:: See Also: Python 3's :mod:`venv module `, + the ``setuptools`` `installation + instructions `_, + `easy_install help `_, + and Pyramid's :ref:`Before You Install `. diff --git a/docs/quick_tutorial/request_response.rst b/docs/quick_tutorial/request_response.rst index 74409711f..7d11cd3c3 100644 --- a/docs/quick_tutorial/request_response.rst +++ b/docs/quick_tutorial/request_response.rst @@ -75,7 +75,7 @@ Analysis In this view class we have two routes and two views, with the first leading to the second by an HTTP redirect. Pyramid can -:ref:`generate redirects ` by returning a +:ref:`generate redirects ` by returning a special object from a view or raising a special exception. In this Pyramid view, we get the URL being visited from ``request.url``. @@ -97,5 +97,5 @@ Extra Credit #. Could we also ``raise HTTPFound(location='/plain')`` instead of returning it? If so, what's the difference? -.. seealso:: :ref:`pyramid:webob_chapter`, - :ref:`generate redirects ` +.. seealso:: :ref:`webob_chapter`, + :ref:`generate redirects ` diff --git a/docs/quick_tutorial/rest_ajax.rst b/docs/quick_tutorial/rest_ajax.rst deleted file mode 100644 index 69a940818..000000000 --- a/docs/quick_tutorial/rest_ajax.rst +++ /dev/null @@ -1,62 +0,0 @@ -================== -29: REST with Ajax -================== - -Use Ajax operations to talk to a REST interface. - -Objectives -========== - -- Populate a list with JSON data - -- Update contents with client-side forms that post to REST operations - -Steps -===== - -#. We are going to use the previous step as our starting point: - - .. code-block:: bash - - (env27)$ cd ..; cp -r rest_ajax_layout rest_ajax; cd rest_ajax - (env27)$ python setup.py develop - -#. Let's first add a Javascript file that implements our browser-side - logic and talks to the REST service: - -#. Introduce ``pyramid_jinja2`` dependency in - ``rest_ajax/tutorial/static/site.js``: - - .. literalinclude:: rest_ajax/tutorial/static/site.js - :language: js - :linenos: - -#. Add a ``