From 5b47ba8ce8c8bdb149b92a2b35a5e7607ca6fc00 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Mon, 12 Aug 2013 14:20:04 -0400 Subject: About to give Intersphinx a shot. --- docs/conf.py | 1 + docs/index.rst | 14 ++++++++------ docs/quick_tour.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++++++---- 3 files changed, 59 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 9b2f2f083..fe094a943 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,6 +55,7 @@ extensions = [ # Looks for objects in external projects intersphinx_mapping = { + 'tutorials': ('http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/', None), 'zcomponent': ('http://docs.zope.org/zope.component', None), 'webtest': ('http://webtest.pythonpaste.org/en/latest', None), 'webob': ('http://docs.webob.org/en/latest', None), diff --git a/docs/index.rst b/docs/index.rst index c4b81ad7d..f9f92e505 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -49,14 +49,15 @@ Getting Started =============== If you are new to Pyramid, we have a few resources that can help you get -up to speed right away. Our *Quick Tour* shows a little about a lot: +up to speed right away. .. toctree:: - :maxdepth: 2 + :hidden: quick_tour -Also: +* :doc:`quick_tour` goes through the major features in Pyramid, covering + a little about a lot. * To see a minimal Pyramid web application, check out `creating your first Pyramid application <../narr/firstapp>`_. @@ -67,10 +68,11 @@ Also: * To get the feel of how a Pyramid web application is created, go to the `single file tasks tutorial `_ page. -* Like learning by example? Check out to the `wiki tutorial - <../tutorials/wiki2/index.html>`_. +* Like learning by example? Check out to the :doc:`wiki tutorial + <../tutorials/wiki2/index>`. -* Need help? See `Support `_. +* Need help? See :ref:`Support and + Development `. .. _html_narrative_documentation: diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index cc4afe67d..13d936a6b 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -2,6 +2,10 @@ Quick Tour of Pyramid ===================== +TODO: + +- Convert all the See Also below into Intersphinx links + Pyramid lets you start small and finish big. This *Quick Tour* guide walks you through many of Pyramid's key features. Let's put the emphasis on *start* by doing a quick tour through Pyramid, with @@ -32,6 +36,10 @@ We make a :term:`virtualenv` then activate it. We then get Python packaging tools installed so we can use the popular ``pip`` tool for installing packages. Normal first steps for any Python project. +See Also: http://docs.python.org/dev/library/venv.html, +https://pypi.python.org/pypi/setuptools/0.9.8#installation-instructions, +http://www.pip-installer.org/en/latest/, narr/install.html#before-you-install + Pyramid Installation ==================== @@ -45,6 +53,8 @@ installed is easy: Our virtual environment now has the Pyramid software available to its Python. +See Also: narr/install.html#installing-pyramid-on-a-unix-system, + Hello World =========== @@ -82,6 +92,9 @@ in Pyramid development. Building an application from loosely-coupled parts via :doc:`../narr/configuration` is a central idea in Pyramid, one that we will revisit regurlarly in this *Quick Tour*. +See Also: narr/firstapp, +http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/single_file_tasks/single_file_tasks.html + Handling Web Requests and Responses =================================== @@ -110,6 +123,10 @@ the name is included in the body of the response:: Finally, we set the response's content type and return the Response. +See Also: http://localhost:8080/projects/pyramid/docs +.gettingstarted/docs/_build/narr/webob.html#webob-chapter, + + Views ===== @@ -158,6 +175,8 @@ configuration`, in which a Python :term:`decorator` is placed on the line above the view. Both approaches result in the same final configuration, thus usually, it is simply a matter of taste. +See Also: narr/views.html, narr/viewconfig, +narr/viewconfig.html#debugging-view-configuration Routing ======= @@ -200,10 +219,8 @@ view: "replacement patterns" (the curly braces) in the route declaration. This information can then be used in your view. -As you might imagine, Pyramid provides -:doc:`many more features in routing <../narr/urldispatch>` -(route factories, custom predicates, security statements, -etc.) We will see more features later in *Geting Started*. +See Also: narr/urldispatch, narr/urldispatch +.html#debugging-route-matching, narr/router Templating ========== @@ -234,6 +251,9 @@ Since our view returned ``dict(name=request.matchdict['name'])``, we can use ``name`` as a variable in our template via ``${name}``. +See Also: narr/templates, narr/templates.html#debugging-templates, +templates.html#templating-with-mako-templates, + Templating With ``jinja2`` ========================== @@ -276,6 +296,7 @@ renderer. At the time of this writing, Jinja2 had not released a version compatible with Python 3.3. +See Also: Jinja2, pyramid_jinja2, Static Assets ============= @@ -320,6 +341,9 @@ By using ``request.static_url`` to generate the full URL to the static assets, you both ensure you stay in sync with the configuration and gain refactoring flexibility later. +See Also: narr/assets, narr/environment.html#preventing-http-caching, +narr/viewconfig.html#influencing-http-caching, + Returning JSON ============== @@ -335,6 +359,9 @@ This wires up a view that returns some data through the JSON :term:`renderer`, which calls Python's JSON support to serialize the data into JSON and set the appropriate HTTP headers. +See Also: narr/renderers.html#json-renderer, +narr/renderers.html#adding-and-overriding-renderers + View Classes ============ @@ -376,6 +403,8 @@ Only one route needed, stated in one place atop the view class. Also, the assignment of the ``name`` is done in the ``__init__``. Our templates can then use ``{{ view.name }}``. +See Also: narr/views.html#defining-a-view-callable-as-a-class + Quick Project Startup with Scaffolds ==================================== @@ -422,6 +451,8 @@ configuration. This includes a new way of running your application: Let's look at ``pserve`` and configuration in more depth. +See Also: narr/project.html#creating-a-pyramid-project, narr/scaffolding.html + Application Running with ``pserve`` =================================== @@ -493,6 +524,9 @@ Additionally, the ``development.ini`` generated by this scaffold wired up Python's standard logging. We'll now see in the console, for example, a log on every request that comes in, as well traceback information. +See Also: narr/environment.html#environment-variables-and-ini-file +-settings, narr/paste.html + Easier Development with ``debugtoolbar`` ======================================== @@ -542,6 +576,8 @@ you want to disable this toolbar, no need to change code: you can remove it from ``pyramid.includes`` in the relevant ``.ini`` configuration file. +See Also: pyramid_debugtoolbar + Unit Tests and ``nose`` ======================= @@ -592,6 +628,9 @@ Pyramid supplies helpers for test writing, which we use in the test setup and teardown. Our one test imports the view, makes a dummy request, and sees if the view returns what we expected. +See Also: nose, narr/testing +.html#unit-integration-and-functional-testing, + Logging ======= @@ -633,6 +672,8 @@ visit ``http://localhost:6543`` your console will now show:: 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message +See Also: narr/sessions.html, narr/sessions.html#flash-messages, + Sessions ======== @@ -677,6 +718,7 @@ Jinja2 template: :start-after: Start Sphinx Include 1 :end-before: End Sphinx Include 1 +See Also: narr/sessions.html#sessions, api/session.html Databases ========= @@ -721,6 +763,9 @@ of the system, can then easily get at the data thanks to SQLAlchemy: :start-after: Start Sphinx Include :end-before: End Sphinx Include +See Also: sqlalchemy, narr/commandline + .html#making-your-script-into-a-console-script, pyramid_tm, + Forms ===== @@ -780,6 +825,7 @@ Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform widgets using attractive CSS from Bootstrap and more powerful widgets from Chosen. +See Also: Deform, Colander Conclusion ========== -- cgit v1.2.3