Merge remote-tracking branch 'refs/remotes/Pylons/master'

1 files changed, 157 insertions, 126 deletions

diff --git a/docs/index.rst b/docs/index.rst
index a4743af9b..aecc26d2e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,199 +1,223 @@
 .. _index:
 
-=================================================
-The Pyramid Web Application Development Framework
-=================================================
+=========================
+The Pyramid Web Framework
+=========================
 
-:app:`Pyramid` is a small, fast, down-to-earth Python web application
-development framework.  It is developed as part of the `Pylons Project
-<http://docs.pylonsproject.org/>`_.  It is licensed under a `BSD-like license
-<http://repoze.org/license.html>`_.
+:app:`Pyramid` is a small, fast, down-to-earth Python web framework.  It is
+developed as part of the `Pylons Project <http://docs.pylonsproject.org/>`_.
+It is licensed under a `BSD-like license <http://repoze.org/license.html>`_.
 
-Front Matter
-============
+Here is one of the simplest :app:`Pyramid` applications you can make:
+
+.. literalinclude:: narr/helloworld.py
+
+After you install :app:`Pyramid` and run this application, when you visit
+`<http://localhost:8080/hello/world>`_ in a browser, you will see the text
+``Hello, world!`` See :ref:`firstapp_chapter` for a full explanation of how
+this application works.
+
+
+.. _html_getting_started:
+
+Getting Started
+===============
+
+If you are new to Pyramid, we have a few resources that can help you get up to
+speed right away.
 
 .. toctree::
-   :maxdepth: 1
+   :hidden:
+
+   quick_tour
+   quick_tutorial/index
+
+* :doc:`quick_tour` gives an overview of the major features in Pyramid,
+  covering a little about a lot.
+
+* :doc:`quick_tutorial/index` is similar to the Quick Tour, but in a tutorial
+  format, with somewhat deeper treatment of each topic and with working code.
+
+* Like learning by example? Visit the official :ref:`html_tutorials` as well as
+  the community-contributed :ref:`Pyramid Tutorials
+  <tutorials:pyramid-tutorials>` and :ref:`Pyramid Community Cookbook
+  <cookbook:pyramid-cookbook>`.
+
+* For help getting Pyramid set up, try :ref:`installing_chapter`.
+
+* Need help?  See :ref:`Support and Development <support-and-development>`.
+
+
+.. _html_tutorials:
 
-   copyright.rst
-   conventions.rst
+Tutorials
+=========
 
-"What's New" Documents
-======================
+Official tutorials explaining how to use :app:`Pyramid` to build various types
+of applications, and how to deploy :app:`Pyramid` applications to various
+platforms.
 
 .. toctree::
    :maxdepth: 1
 
-   whatsnew-1.0
-   whatsnew-1.1
+   tutorials/wiki2/index.rst
+   tutorials/wiki/index.rst
+   tutorials/modwsgi/index.rst
+
 
-Narrative documentation
+.. _support-and-development:
+
+Support and Development
 =======================
 
-Narrative documentation in chapter form explaining how to use
-:app:`Pyramid`.
+The `Pylons Project web site <http://pylonsproject.org/>`_ is the main online
+source of :app:`Pyramid` support and development information.
+
+To report bugs, use the `issue tracker
+<https://github.com/Pylons/pyramid/issues>`_.
+
+If you've got questions that aren't answered by this documentation, contact the
+`Pylons-discuss maillist <http://groups.google.com/group/pylons-discuss>`_ or
+join the `#pyramid IRC channel <irc://irc.freenode.net/#pyramid>`_.
+
+Browse and check out tagged and trunk versions of :app:`Pyramid` via the
+`Pyramid GitHub repository <https://github.com/Pylons/pyramid/>`_. To check out
+the trunk via ``git``, use either command:
+
+.. code-block:: text
+
+  # If you have SSH keys configured on GitHub:
+  git clone git@github.com:Pylons/pyramid.git
+  
+  # Otherwise, HTTPS will work, using your GitHub login:
+  git clone https://github.com/Pylons/pyramid.git
+
+To find out how to become a contributor to :app:`Pyramid`, please see the
+`contributor's section of the documentation
+<http://docs.pylonsproject.org/en/latest/#contributing>`_.
+
+
+.. _html_narrative_documentation:
+
+Narrative Documentation
+=======================
+
+Narrative documentation in chapter form explaining how to use :app:`Pyramid`.
 
 .. toctree::
    :maxdepth: 2
 
    narr/introduction
    narr/install
-   narr/configuration
    narr/firstapp
+   narr/configuration
    narr/project
    narr/startup
+   narr/router
    narr/urldispatch
-   narr/muchadoabouttraversal
-   narr/traversal
    narr/views
    narr/renderers
    narr/templates
    narr/viewconfig
-   narr/resources
    narr/assets
    narr/webob
    narr/sessions
-   narr/security
-   narr/hybrid
-   narr/i18n
-   narr/vhosting
    narr/events
    narr/environment
+   narr/logging
+   narr/paste
+   narr/commandline
+   narr/i18n
+   narr/vhosting
    narr/testing
+   narr/resources
+   narr/hellotraversal
+   narr/muchadoabouttraversal
+   narr/traversal
+   narr/security
+   narr/hybrid
+   narr/subrequest
    narr/hooks
-   narr/advconfig
+   narr/introspector
    narr/extending
-   narr/router
+   narr/advconfig
+   narr/extconfig
+   narr/scaffolding
+   narr/upgrading
    narr/threadlocals
    narr/zca
 
-Tutorials
-=========
 
-Detailed tutorials explaining how to use :app:`Pyramid` to build
-various types of applications and how to deploy :app:`Pyramid`
-applications to various platforms.
+API Documentation
+=================
+
+Comprehensive reference material for every public API exposed by
+:app:`Pyramid`:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :glob:
 
-   tutorials/wiki2/index.rst
-   tutorials/wiki/index.rst
-   tutorials/bfg/index.rst
-   tutorials/gae/index.rst
-   tutorials/modwsgi/index.rst
+   api/index
+   api/*
 
-Reference Material
-==================
 
-Reference material includes documentation for every :app:`Pyramid` API.
+``p*`` Scripts Documentation
+============================
+
+``p*`` scripts included with :app:`Pyramid`:.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :glob:
 
-   api
+   pscripts/index
+   pscripts/*
 
-Detailed Change History
-=======================
+
+Change History
+==============
 
 .. toctree::
    :maxdepth: 1
 
+   whatsnew-1.7
+   whatsnew-1.6
+   whatsnew-1.5
+   whatsnew-1.4
+   whatsnew-1.3
+   whatsnew-1.2
+   whatsnew-1.1
+   whatsnew-1.0
    changes
 
-Design Documentation
-====================
+
+Design Documents
+================
 
 .. toctree::
    :maxdepth: 1
 
    designdefense
 
-Sample Applications
-===================
 
-`cluegun <https://github.com/Pylons/cluegun>`_ is a simple pastebin
-application based on Rocky Burt's `ClueBin
-<http://pypi.python.org/pypi/ClueBin/0.2.3>`_.  It demonstrates form
-processing, security, and the use of :term:`ZODB` within a :app:`Pyramid`
-application.  Check this application out via:
-
-.. code-block:: text
+Copyright, Trademarks, and Attributions
+=======================================
 
-  git clone git://github.com/Pylons/cluegun.git
-
-`virginia <https://github.com/Pylons/virginia>`_ is a very simple dynamic
-file rendering application.  It is willing to render structured text
-documents, HTML documents, and images from a filesystem directory.  An
-earlier version of this application runs the `repoze.org
-<http://repoze.org>`_ website.  Check this application out via:
-
-.. code-block:: text
-
-  git clone git://github.com/Pylons/virginia.git
-
-`shootout <https://github.com/Pylons/shootout>`_ is an example "idea
-competition" application by Carlos de la Guardia and Lukasz Fidosz.  It
-demonstrates :term:`URL dispatch`, simple authentication, integration
-with `SQLAlchemy <http://www.sqlalchemy.org/>`_ and ``pyramid_simpleform``.
-Check this application out of version control via:
-
-.. code-block:: text
-
-  git clone git://github.com/Pylons/shootout.git
-
-Older Sample Applications (repoze.bfg)
-======================================
-
-.. note::
-
-   These applications are for an older version of :app:`Pyramid`, which was
-   named :mod:`repoze.bfg`.  They won't work unmodified under Pyramid, but
-   might provide useful clues.
-
-`bfgsite <http://svn.repoze.org/bfgsite/trunk>`_ is the software which
-runs the `bfg.repoze.org <http://bfg.repoze.org>`_ website.  It
-demonstrates integration with Trac, and includes several
-mini-applications such as a pastebin and tutorial engine.  Check a
-buildout for this application out of Subversion via:
-
-.. code-block:: text
-
-  svn co http://svn.repoze.org/buildouts/bfgsite/ bfgsite_buildout
-
-`KARL <http://karlproject.org>`_ is a moderately-sized application
-(roughly 70K lines of Python code) built on top of :mod:`repoze.bfg`
-and other Repoze software.  It is an open source web system for
-collaboration, organizational intranets, and knowledge management, It
-provides facilities for wikis, calendars, manuals, searching, tagging,
-commenting, and file uploads.  See the `KARL site
-<http://karlproject.org>`_ for download and installation details.
-
-Support and Development
-=======================
-
-The `Pylons Project web site <http://pylonsproject.org/>`_ is the main online
-source of :app:`Pyramid` support and development information.
+.. toctree::
+   :maxdepth: 1
 
-To report bugs, use the `issue tracker
-<http://github.com/Pylons/pyramid/issues>`_.
+   copyright
 
-If you've got questions that aren't answered by this documentation,
-contact the `Pylons-devel maillist
-<http://groups.google.com/group/pylons-devel>`_ or join the `#pylons
-IRC channel <irc://irc.freenode.net/#pylons>`_.
 
-Browse and check out tagged and trunk versions of :app:`Pyramid` via
-the `Pyramid GitHub repository <http://github.com/Pylons/pyramid/>`_.
-To check out the trunk via ``git``, use this command:
+Typographical Conventions
+=========================
 
-.. code-block:: text
+.. toctree::
+   :maxdepth: 1
 
-  git clone git@github.com:Pylons/pyramid.git
+   conventions
 
-To find out how to become a contributor to :app:`Pyramid`, please see the
-`contributor's section of the documentation
-<http://docs.pylonsproject.org/index.html#contributing>`_.
 
 Index and Glossary
 ==================
@@ -201,3 +225,10 @@ Index and Glossary
 * :ref:`glossary`
 * :ref:`genindex`
 * :ref:`search`
+
+
+.. toctree::
+   :hidden:
+
+   glossary
+