Changed front page, with different entry points and documentationmainline-refactor

6 files changed, 293 insertions, 0 deletions

diff --git a/docs/develop-example.txt b/docs/develop-example.txt
new file mode 100644
index 0000000..efc871b
--- /dev/null
+++ b/docs/develop-example.txt
@@ -0,0 +1,72 @@
+Development With Paste: An Example
+++++++++++++++++++++++++++++++++++
+
+This example uses `WebKit </webkit/>`_, `SQLObject
+<http://sqlobject.org>`_, and `Zope Page Templates <>`_, but it's all
+pluggable for other frameworks and tools.  
+
+Paste enabled applications are all proper Python packages, and even
+moreso they are installable by `easy_install <>`_, including Paste
+itself::
+
+    $ easy_install PasteScript PasteWebKit SQLObject ZPTKit 
+    ... messages fly by ...
+
+This example also uses Subversion repository (we'll assume you've set
+up a repository with ``svnadmin create /home/me/testrepos``).  When
+you create a project, you can create a layout in your repository for
+it.
+
+This will create the new project::
+    
+    $ paster create --template=webkit --template=zpt \
+        --svn-repository=file:///home/me/testrepos Wiki 
+    ... the package is setup in the repository ...
+    ... file listings fly by ...
+    $ cd Wiki
+    $ svn commit -m "New project"
+    ... messages about committing ...
+
+The basic setup has a simplest of applications already set up; you can
+test everything is working by running::
+
+    $ paster serve --reload docs/devel_config.ini
+    ... now your new app is served on http://localhost:8080/ ...
+    ... ^C to quit
+
+It also has set up a `py.test <>`_ fixture for you, so you can run the
+first test (which just tests that the front page loads up properly):
+
+    $ py.test -v
+    ... test results ...
+
+Using the ``webkit`` template we've also added a new command for
+setting up new servlets::
+
+    $ paster servlet listing
+    ... @@: creating files ... 
+
+Also, all the metadata for SQLObject has been added to the template,
+and can be used like::
+
+    $ sqlobject-admin create --egg=Wiki
+    ... database create statements ...
+
+You can add version information to your model as well, so that you can
+develop and record your updates, and then apply them to old versions
+of the database.
+
+Once you've made something you are ready to deploy, you can use
+`buildutils <>`_ to tag it for release::
+
+    $ python setup.py svntag --version=0.1 -b ../Wiki01
+    $ cd ../Wiki01
+    $ python setup.py sdist
+    ... boring messages ...
+    ... @@: Deploy stuff ...
+
+And then deploy it on another server::
+
+    $ ssh other-server
+    ... @@: More deploy stuff ...
+
diff --git a/docs/developer-features.txt b/docs/developer-features.txt
new file mode 100644
index 0000000..bc08010
--- /dev/null
+++ b/docs/developer-features.txt
@@ -0,0 +1,131 @@
+Documentation
+=============
+
+Tutorials and Introduction
+==========================
+
+* `To-Do Tutorial <http://pythonpaste.org/todo/TodoTutorial.html>`_
+
+The core Paste package is a set of tools that use `WSGI
+<http://www.python.org/peps/pep-0333.html>`_ heavily as the means of
+communication.  WSGI is an in-process CGI-like communication protocol.
+
+Right now the best way to see the various tools available in Paste is
+to `look through the source <module-index.html>`_.
+
+Related Projects
+================
+
+Closely related packages:
+
+* `Paste Deploy <http://pythonpaste.org/deploy/>`_
+* `Paste Script <http://pythonpaste.org/script/>`_
+* `Paste WebKit <http://pythonpaste.org/webkit/>`_
+* `Wareweb <http://pythonpaste.org/wareweb/>`_
+
+Developer Documentation
+=======================
+
+* `Developer Guidelines <DeveloperGuidelines.html>`_
+* `Style Guide <StyleGuide.html>`_
+
+Reference Documentation
+=======================
+
+* `Testing Applications With Paste <testing-applications.html>`_
+* `URL Parsing with WSGI and Paste <url-parsing-with-wsgi.html>`_
+
+
+License
+=======
+
+Paste is distributed under the `Python Software Foundation`__
+license.  This is a BSD/MIT-style license.
+
+.. __: http://www.python.org/psf/license.html
+
+Overview
+========
+
+If you don't want to look through source, here's a quick overview of
+what there is here:
+
+Testing
+-------
+
+* A fixture for testing WSGI applications conveniently and in-process,
+  in ``paste.fixture``
+
+* A fixture for testing command-line applications, also in
+  ``paste.fixture``
+
+* Check components for WSGI-compliance in ``paste.lint``
+
+Dispatching
+-----------
+
+* Chain and cascade WSGI applications (returning the first non-error
+  response) in ``paste.cascade``
+
+* Dispatch to several WSGI applications based on URL prefixes, in
+  ``paste.urlmap``
+
+* Allow applications to make subrequests and forward requests
+  internally, in ``paste.recursive``
+
+Web Application
+---------------
+
+* Run CGI programs as WSGI applications in ``paste.cgiapp`` (and
+  Python-sepcific CGI programs with ``paste.pycgiwrapper``)
+
+* Traverse files and load WSGI applications from ``.py`` files (or
+  static files), in ``paste.urlparser``
+
+* Serve static directories of files, also in ``paste.urlparser``
+
+Tools
+-----
+
+* Catch HTTP-related exceptions (e.g., ``HTTPNotFound``) and turn them
+  into proper responses in ``paste.httpexceptions``
+
+* Check for signed cookies for authentication, setting ``REMOTE_USER``
+  in ``paste.login``
+
+* Create sessions in ``paste.session`` and ``paste.flup_session``
+
+* Gzip responses in ``paste.gzip``
+
+* A wide variety of routines for manipulating WSGI requests and
+  producing responses, in ``paste.wsgilib``
+
+Debugging Filters
+-----------------
+
+* Catch (optionally email) errors with extended tracebacks (using
+  Zope/ZPT conventions) in ``paste.exceptions``
+
+* Catch errors presenting a `cgitb
+  <http://python.org/doc/current/lib/module-cgitb.html>`_-based
+  output, in ``paste.cgitb_catcher``.
+
+* Profile each request and append profiling information to the HTML,
+  in ``paste.profilemiddleware``
+
+* Capture ``print`` output and present it in the browser for
+  debugging, in ``paste.printdebug``
+
+* Validate all HTML output from applications using the `WDG Validator
+  <http://www.htmlhelp.com/tools/validator/>`_, appending any errors
+  or warnings to the page, in ``paste.wdg_validator``
+
+Other Tools
+-----------
+
+* A file monitor to allow restarting the server when files have been
+  updated (for automatic restarting when editing code) in
+  ``paste.reloader``
+
+* A class for generating and traversing URLs, and creating associated
+  HTML code, in ``paste.url``
diff --git a/docs/enabled.txt b/docs/enabled.txt
new file mode 100644
index 0000000..db2f2e9
--- /dev/null
+++ b/docs/enabled.txt
@@ -0,0 +1,4 @@
+Paste Enabled
++++++++++++++
+
+... what does it mean ...
diff --git a/docs/index.txt b/docs/index.txt
index bc08010..710c873 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -1,3 +1,53 @@
+Python Paste
+============
+
+Python Paste -- 50% tastier than Elmer's!  
+Paste: making the web sticky.  
+Fix broken websites by applying a Paste liberally.
+Paste: paper over your inconsistencies. 
+Paste: a soft mixture of malleable consistency.  
+Paste: a tasty mixture to be spread on bread or crackers.  
+Paste: the glue that won't hurt you when you eat it.
+Python Paste: the web extruded into the form of a snake.
+Paste: the vinegar eel.
+Paste: you bring the cut.
+Paste: a doughy substance from which to make metaphorical web cupcakes.
+
+Python Paste brings consistency to Python web development and web
+application installation, providing tools for both developers and
+system administrators.
+
+Paste for Administrators
+------------------------
+
+* Easily install, run, and configure multiple Paste-enabled web
+  applications at once, and integrate them into your website how you
+  want (SCGI, FCGI, AJP, WSGI)
+
+* Manage and install web applications system-wide for easy maintenance
+
+* `See an installation example <install-example.html>`_ or `read more
+  about what Paste-enabled means... <enabled.html>`_
+
+Paste for Web Developers
+------------------------
+
+* Increase your web application's audience
+
+* Provide starter templates and custom commands for using your web
+  framework
+
+* Keep your development and deployment straightened out, and your
+  automated testing streamlined
+
+* Attention payed to the full development cycle -- starting projects,
+  converting old projects, updating and deploying projects -- using a
+  set of `complimentary packages and tools <related-projects.html>`_
+
+* `See a development example <develop-example.html>`_ or `read more
+  about using Paste in your
+  applications... <developer-features.html>`_
+
 Documentation
 =============
 
diff --git a/docs/install-example.txt b/docs/install-example.txt
new file mode 100644
index 0000000..4024f0d
--- /dev/null
+++ b/docs/install-example.txt
@@ -0,0 +1,33 @@
+Paste Installation
+++++++++++++++++++
+
+Installation of Paste-enabled applications is consistent and reliable;
+you don't have to understand what technologies those applications
+used.  Paste-enabled applications are installable with `easy_install
+<>`_, like::
+
+    $ easy_install FileBrowser
+    ... messages ...
+
+Once an application is installed, you can set up an instance of that
+application with ``paste deploy``::
+
+    $ paste deploy FileBrowser location
+    ... @@: make this work ;) ...
+
+This just wrote to ``location/filebrowser.ini`` -- you can configure
+the application there, with whatever specifics that application needs.
+Then you can integrate it into your website and other applications,
+with a file like::
+
+    [composit:main]
+    use = egg:Paste#urlmap
+    /browser = config:filebrowser.ini
+
+You can attach applications to many locations using this.  Once you've
+set that file up with your local settings and preferences, you can
+run::
+
+    $ paster serve location/apps.ini --daemon
+
+And it will be running in the background.
diff --git a/setup.cfg b/setup.cfg
index 8c87f4a..0ef5777 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -10,6 +10,9 @@ docs = docs/index.txt docs/DeveloperGuidelines.txt docs/StyleGuide.txt
        docs/community/index.txt docs/community/mailing-list.txt
        docs/community/repository.txt
        docs/download/index.txt
+       docs/develop-example.txt docs/developer-features.txt
+       docs/enabled.txt docs/install-example.txt
+
 doc_base = docs/
 dest = docs/html
 modules = paste