From bf84d90b4dccb9fc52c8fe385e52f7a63e9a5535 Mon Sep 17 00:00:00 2001
From: Paul Everitt <paul@agendaless.com>
Date: Tue, 13 Aug 2013 07:36:48 -0400
Subject: Add Intersphinx for Beaker, clean up some broken references, change
 from pip to virtualenv (and give an explanation), explain virtualenv on
 Python 2.7.

---
 docs/conf.py        |  3 +++
 docs/index.rst      |  8 ++++----
 docs/quick_tour.rst | 35 ++++++++++++++++++++---------------
 3 files changed, 27 insertions(+), 19 deletions(-)

(limited to 'docs')

diff --git a/docs/conf.py b/docs/conf.py
index e60cd7118..1ddcf95da 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -71,6 +71,9 @@ intersphinx_mapping = {
         'http://docs.pylonsproject.org/projects/deform/en/latest',
     None),
     'sqla': ('http://docs.sqlalchemy.org/en/latest', None),
+    'beaker': (
+        'http://docs.pylonsproject.org/projects/pyramid_beaker/en/latest',
+        None),
     'who': ('http://docs.repoze.org/who/latest', None),
     'python': ('http://docs.python.org', None),
     'python3': ('http://docs.python.org/3', None),
diff --git a/docs/index.rst b/docs/index.rst
index d570e7811..550a5312e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -47,11 +47,11 @@ up to speed right away.
 * :doc:`quick_tour` goes through the major features in Pyramid, covering
   a little about a lot.
 
-* For help getting Pyramid set up, try the `install guide
-  <../narr/install>`_.
+* To see a minimal Pyramid web application, check out
+  :ref:`firstapp_chapter`.
 
-* To see a minimal Pyramid web application, check out `creating your first
-  Pyramid application <../narr/firstapp>`_.
+* For help getting Pyramid set up, try
+  :ref:`installing_chapter`.
 
 * Like learning by example? Visit the official
   :doc:`wiki tutorial <../tutorials/wiki2/index>` as well as the
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index cb07826cf..ba2a517ef 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -29,15 +29,25 @@ area in place. For Python 3.3:
   $ source env33/bin/activate
   $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python
 
-We make a :term:`virtualenv` then activate it. We then get Python
-packaging tools installed.
+We make a :term:`virtualenv` then activate it. Next we download
+Python's packaging support and install 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::
+
+   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 <python3:venv>`,
    the ``setuptools`` `installation
    instructions <https://pypi.python.org/pypi/setuptools/0.9.8#installation-instructions>`_,
-   documentation for `pip <http://www.pip-installer.org/en/latest/>`_,
-   and
-   Pyramid's :ref:`Before You Install <installing_chapter>`
+   `easy_install help <https://pypi.python.org/pypi/setuptools/0.9.8#using-setuptools-and-easyinstall>`_,
+   and Pyramid's :ref:`Before You Install <installing_chapter>`.
 
 Pyramid Installation
 ====================
@@ -722,8 +732,7 @@ Jinja2 template:
 .. seealso:: See Also:
    :ref:`sessions_chapter`, :ref:`flash_messages`,
    :ref:`session_module`, and
-   `Beaker sessioning middleware
-   <http://docs.pylonsproject.org/projects/pyramid_beaker/en/latest/>`_
+   :ref:`Beaker sessioning middleware <beaker:overview>`
 
 Databases
 =========
@@ -771,8 +780,7 @@ of the system, can then easily get at the data thanks to SQLAlchemy:
 .. seealso:: See Also: `SQLAlchemy <http://www.sqlalchemy.org/>`_,
    :ref:`making_a_console_script`,
    :ref:`bfg_sql_wiki_tutorial`, and
-   `Application Transactions With pyramid_tm
-   <http://docs.pylonsproject.org/projects/pyramid_tm/en/latest/>`_
+   :ref:`Application Transactions With pyramid_tm <tm:overview>`
 
 Forms
 =====
@@ -823,10 +831,7 @@ We'd like to handle form submission, validation, and saving:
 
 Deform and Colander provide a very flexible combination for forms,
 widgets, schemas, and validation. Recent versions of Deform also
-include a
-`retail mode <http://docs.pylonsproject
-.org/projects/deform/en/latest/retail.html>`_
-for gaining Deform
+include a :ref:`retail mode <deform:retail>` for gaining Deform
 features on custom forms.
 
 Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform
@@ -834,8 +839,8 @@ widgets using attractive CSS from Bootstrap and more powerful widgets
 from Chosen.
 
 .. seealso:: See Also:
-   `Deform <http://docs.pylonsproject.org/projects/deform/en/latest/>`_,
-   `Colander <http://docs.pylonsproject.org/projects/colander/en/latest/>`_, and
+   :ref:`Deform <deform:overview>`,
+   :ref:`Colander <colander:overview>`, and
    `deform_bootstrap <https://pypi.python.org/pypi/deform_bootstrap>`_
 
 Conclusion
-- 
cgit v1.2.3